Home components annotations

Annotations

Annotations help you add important context directly within a chart - highlight important dates, time periods, or specific points on a chart to make it easier for your audience to pull insights from the information.

Evidence currently offers 2 types of annotations, which can be defined inline or with a dataset:

  • ReferenceLine: draw a horizontal or vertical line on a chart (e.g., annual sales target line, launch dates)
  • ReferenceArea: highlight an area on a chart (e.g., holiday shopping periods, metric control ranges)

Reference Line

Reference lines allow you to add horizontal or vertical lines to a chart to provide additional context within the visualization. These lines can be produced by providing a specific value (y=50 or x='2020-03-14') or by providing a dataset (e.g., date, event_name).

When a dataset is provided, ReferenceLine can generate multiple lines - one for each row in the dataset. This can be helpful for plotting things like important milestones, launch dates, or experiment start dates.

Examples

Y-axis Defined Inline

	

		
		

<LineChart data={orders_by_month} x=month y=sales_usd0k yAxisTitle="Sales per Month">
    <ReferenceLine y=90000 label="Target"/>
</LineChart>

X-axis Defined Inline

	

		
		

<LineChart data={orders_by_month} x=month y=sales_usd0k yAxisTitle="Sales per Month">
    <ReferenceLine x='2019-09-18' label="Launch" hideValue=true/>
</LineChart>

Y-axis Multiple Lines

	

		
		

<LineChart data={orders_by_month} x=month y=sales_usd0k yAxisTitle="Sales per Month">
    <ReferenceLine y=90000 label="Target" labelPosition=belowEnd/>
    <ReferenceLine y=105000 label="Forecast"/>
</LineChart>

X-axis from Data

	

		
		

<LineChart data={orders_by_month} x=month y=sales_usd0k yAxisTitle="Sales per Month">
    <ReferenceLine data={multiple_dates} x=start_date/>
</LineChart>

Custom Styling

	

		
		

<LineChart data={orders_by_month} x=month y=sales_usd0k yAxisTitle="Sales per Month">
    <ReferenceLine y=110000 color=red hideValue=true lineWidth=3 lineType=solid/>
</LineChart>

Label Positions

	

		
		

<LineChart data={orders_by_month} x=month y=sales_usd0k yAxisTitle="Sales per Month">
    <ReferenceLine y=40000 label=aboveStart labelPosition=aboveStart hideValue=true/>
    <ReferenceLine y=40000 label=aboveCenter labelPosition=aboveCenter hideValue=true/>
    <ReferenceLine y=40000 label=aboveEnd labelPosition=aboveEnd hideValue=true/>
    <ReferenceLine y=40000 label=belowStart labelPosition=belowStart hideValue=true/>
    <ReferenceLine y=40000 label=belowCenter labelPosition=belowCenter hideValue=true/>
    <ReferenceLine y=40000 label=belowEnd labelPosition=belowEnd hideValue=true/>
</LineChart>

Colours

	

		
		

<LineChart data={orders_by_month} x=month y=sales_usd0k yAxisTitle="Sales per Month">
    <ReferenceLine y=15000 color=red label=red/>
    <ReferenceLine y=35000 color=yellow label=yellow/>
    <ReferenceLine y=55000 color=green label=green/>
    <ReferenceLine y=75000 color=blue label=blue/>
    <ReferenceLine y=95000 color=grey label=grey/>
    <ReferenceLine y=115000 color=#63178f label=custom/>
</LineChart>

Options

A reference line can be produced by defining values inline or by supplying a dataset, and the required props are different for each of those cases.

Defining Values Inline

x
x-axis value where line will be plotted
Options:
number | string | date
y
y-axis value where line will be plotted
Options:
number
label
Text to show as label for the line. If no label is provided, the value will be used.
Options:
string
  • One of x or y is required to plot a line.
  • If both x and y are provided, x will be used and y will be ignored.

Supplying a Dataset

data
REQUIRED
Query name, wrapped in curly braces
Options:
query name
x
Column containing x-axis values
Options:
column name
y
Column containing y-axis values
Options:
column name
label
Column containing a label to use for each line
Options:
column name
hideValue
Option to remove the value from the label
Options:
Default:
false
  • If both x and y are provided, x will be used and y will be ignored.

Styling

labelPosition
Where label will appear on the line
Options:
Default:
aboveEnd
color
Color to override default line and label colors
Options:
CSS name | hexademical | RGB | HSL
lineColor
Color to override default line color. If used, takes precedence over `color`
Options:
CSS name | hexademical | RGB | HSL
labelColor
Color to override default label color. If used, takes precedence over `color`
Options:
CSS name | hexademical | RGB | HSL
lineType
Options to show breaks in a line (dashed or dotted)
Options:
Default:
dashed
lineWidth
Thickness of line (in pixels)
Options:
number
Default:
1.3
labelBackground
Option to show a white semi-transparent background behind the label. Helps when label is shown in front of darker colours.
Options:
Default:
true

Reference Area

Reference areas allow you to add highlighted ranges to a chart. These ranges can be:

  • Along the x-axis (e.g., recession date ranges)
  • Along the y-axis (e.g., control threshold for a metric)
  • Both (e.g, highlighting a specific series of points in the middle of the chart)

Reference areas can be produced by defining the x and y-axis values inline (e.g., xMin='2020-03-14' xMax='2020-06-30') or by supplying a dataset (e.g., start_date, end_date, name).

When a dataset is provided, ReferenceArea can generate multiple areas - one for each row in the dataset.

Examples

X-axis Defined Inline

	

		
		

<LineChart data={orders_by_month} x=month y=sales_usd0k yAxisTitle="Sales per Month">
    <ReferenceArea xMin='2020-03-14' xMax='2020-08-15' label=First color=yellow/>
    <ReferenceArea xMin='2021-03-14' xMax='2021-08-15' label=Second/>
</LineChart>

Y-axis Defined Inline

	

		
		

<LineChart data={orders_by_month} x=month y=num_orders_num0 yAxisTitle="Orders per Month">
    <ReferenceArea yMin=2500 color=green label="Good"/>
    <ReferenceArea yMin=1000 yMax=2500 color=yellow label="Okay"/>
    <ReferenceArea yMin=0 yMax=1000 color=red label="Bad"/>
</LineChart>

X-axis from Data

	

		
		

<LineChart data={query_name} x=column_x y=column_y>
    <ReferenceArea data={campaigns} xMin=start_date xMax=end_date label=campaign_name/>
</LineChart>

Bar Chart

	

		
		

<BarChart data={orders_by_category_2021} x=month y=sales_usd0k series=category>
    <ReferenceArea xMin='2021-01-01' xMax='2021-04-01'/>
</BarChart>

Continuous Axis Bar Charts

On a continous x-axis (dates or numbers), the reference area will start and stop at the exact point on the x-axis. This means it will appear in the middle of whichever bar is at that point. If you would prefer to see the area cover the full bar, there are 2 ways to achieve this:

  1. Add a buffer on either side of the range you want to highlight (e.g., instead of ending the area at 2020-07-01, end it at 2020-07-15)
  2. Change your x-axis to categorical data (using xType=category). If using a date axis, you may also want to retain the axis label formatting for dates - to achieve this, you can use the xFmt prop (e.g., xFmt=mmm)

Reference Area Box

	

		
		

<ScatterPlot data={countries} x=gdp_usd y=gdp_growth_pct1 tooltipTitle=country series=continent>
    <ReferenceArea xMin=16000 xMax=24000 yMin=-0.03 yMax=0.055 label="Large and stagnant" color=grey border=true/>
</ScatterPlot>

Labels

	

		
		

<LineChart data={orders_by_month} x=month y=sales_usd0k>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=topLeft labelPosition=topLeft/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=top labelPosition=top/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=topRight labelPosition=topRight/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=left labelPosition=left/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=center labelPosition=center/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=right labelPosition=right/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=bottomLeft labelPosition=bottomLeft/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=bottom labelPosition=bottom/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=bottomRight labelPosition=bottomRight/>
</LineChart>

Label Overlaps

Reference areas appear behind chart gridlines, including reference area labels. If you are seeing an overlap between the gridlines and the reference area label, you can avoi this by turning gridlines off (yGridlines=false).

Colours

	

		
		

<LineChart data={orders_by_month} x=month y=sales_usd0k >
    <ReferenceArea xMax='2019-04-01' label=blue color=blue/>
    <ReferenceArea xMin='2019-04-01' xMax='2019-11-01' label=red color=red/>
    <ReferenceArea xMin='2019-11-01' xMax='2020-07-01' label=yellow color=yellow/>
    <ReferenceArea xMin='2020-07-01' xMax='2021-02-01' label=green color=green/>
    <ReferenceArea xMin='2021-02-01' xMax='2021-09-01' label=grey color=grey/>
    <ReferenceArea xMin='2021-09-01' label=custom color=#f2dbff labelColor=#4d1070/>
</LineChart>

Options

A reference area can be produced by defining values inline or by supplying a dataset, and the required props are different for each of those cases.

Defining Values Inline

xMin
x-axis value where area should start. If left out, range will extend to the start of the x-axis.
Options:
number | string | date
xMax
x-axis value where area should end. If left out, range will extend to the end of the x-axis.
Options:
number | string | date
yMin
y-axis value where area should start. If left out, range will extend to the start of the y-axis.
Options:
number
yMax
y-axis value where area should end. If left out, range will extend to the end of the y-axis.
Options:
number
label
Text to show as label for the area
Options:
string
  • At least 1 of xMin, xMax, yMin, or yMax is required to plot an area.

Supplying a Dataset

data
REQUIRED
Query name, wrapped in curly braces
Options:
query name
xMin
Column containing x-axis values for area start. If left out, range will extend to the start of the x-axis.
Options:
column name
xMax
Column containing x-axis values for area end. If left out, range will extend to the end of the x-axis.
Options:
column name
yMin
Column containing y-axis values for area start. If left out, range will extend to the start of the y-axis.
Options:
column name
yMax
Column containing y-axis values for area end. If left out, range will extend to the end of the y-axis.
Options:
column name
label
Column containing a label to use for each area
Options:
column name
  • At least 1 of xMin, xMax, yMin, or yMax is required to plot an area.

Styling

labelPosition
Where label will appear within the area
Options:
Default:
topLeft
color
Color to override default area and label colors
Options:
CSS name | hexademical | RGB | HSL
labelColor
Color to override default label color. If used, takes precedence over `color`
Options:
CSS name | hexademical | RGB | HSL
border
Whether border should be shown
Options:
Default:
false
borderColor
Color to override default border color
Options:
CSS name | hexademical | RGB | HSL
borderType
Options to show breaks in a line (dashed or dotted)
Options:
Default:
dashed
borderWidth
Thickness of line (in pixels)
Options:
number
Default:
1