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.

At a glance

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

  • ReferenceLine: draw a line on a chart (e.g. sales target, launch dates, linear regression)
  • ReferenceArea: highlight an area on a chart (e.g. holiday shopping periods, metric control ranges)
  • ReferencePoint: highlight specific points on a chart (e.g. anomalies, points of interest)
  • Callout: draw attention to data (e.g. data trend explanation)
Loading...

Reference Line

Reference lines allow you to add 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).

If you provide coordinates for [x, y] and [x2, y2], you can create sloped lines between points.

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

Loading...

X-axis Defined Inline

Loading...

Y-axis Multiple Lines

Loading...

X-axis from Data

Loading...

Sloped Line Inline

Loading...

Linear Regression from Data

Loading...

Custom Styling

Loading...

Label Positions

Loading...

Colours

Loading...

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, or coordinate where line will start if x2 is provided
Options:
number | string | date
y
y-axis value where line will be plotted, or coordinate where line will start if y2 is provided
Options:
number
x2
x-axis value for line endpoint
Options:
number | string | date
y2
y-axis value for line endpoint
Options:
number
label
Text to show as label for the line. If no label is provided, the value will be used.
Options:
string

This table shows how you combine x, y, x2, and y2 to create different types of lines:
No Results

Supplying a Dataset

data
Required
Query name, wrapped in curly braces
Options:
query name
x
Column containing x-axis values for lines (or starting points if x2 is provided)
Options:
column name
y
Column containing y-axis values for lines (or starting points if y2 is provided)
Options:
column name
x2
Column containing x-axis values for line endpoints.
Options:
column name
y2
Column containing y-axis values for line endpoints.
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
No Results

Styling

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
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
symbolStart
The type of symbol used to mark the start of the line
Options:
Default:
circle
symbolStartSize
The size of the symbol at the start of the line
Options:
number
Default:
8
symbolEnd
The type of symbol used to mark the end of the line
Options:
Default:
circle
symbolEndSize
The size of the symbol at the end of the line
Options:
number
Default:
8
labelPosition
Where label will appear on the line
Options:
Default:
aboveEnd
labelColor
Color to override default label color. If used, takes precedence over `color`
Options:
CSS name | hexademical | RGB | HSL
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
labelPadding
Padding between the text and the border of the label background
Options:
number
labelBorderWidth
The thickness of the border around the label (in pixels)
Options:
number
labelBorderRadius
The radius of rounded corners on the label background (in pixels)
Options:
number
labelBorderColor
The color of the border around the label background
Options:
CSS name | hexademical | RGB | HSL
labelBorderType
The type of border around the label background (dashed or dotted)
Options:
fontSize
The size of the font in the label
Options:
number
align
How to align the label to the symbol, and the text within the label
Options:
bold
Make the label text bold
Options:
Default:
false
italic
Make the label text italic
Options:
Default:
false

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

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

Y-axis Defined Inline

Loading... 
<LineChart data={orders_by_month} x=month y=num_orders yAxisTitle="Orders per Month">
    <ReferenceArea yMin=250 color=positive label="Good"/>
    <ReferenceArea yMin=100 yMax=250 color=warning label="Okay"/>
    <ReferenceArea yMin=0 yMax=100 color=negative label="Bad"/>
</LineChart>

X-axis from Data

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0 yAxisTitle="Sales per Month">
    <ReferenceArea data={multiple_dates} xMin=start_date xMax=end_date label=campaign_name/>
</LineChart>

Bar Chart

Loading... 
<BarChart data={orders_by_category_2021} x=month y=sales yFmt=usd0 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=base-content-muted border=true/>
</ScatterPlot>

Labels

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=topLeft labelPosition=topLeft areaColor="hsla(206.25, 80%, 80%, 0.01)"/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=top labelPosition=top areaColor="hsla(206.25, 80%, 80%, 0.01)"/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=topRight labelPosition=topRight areaColor="hsla(206.25, 80%, 80%, 0.01)"/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=left labelPosition=left areaColor="hsla(206.25, 80%, 80%, 0.01)"/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=center labelPosition=center areaColor="hsla(206.25, 80%, 80%, 0.01)"/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=right labelPosition=right areaColor="hsla(206.25, 80%, 80%, 0.01)"/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=bottomLeft labelPosition=bottomLeft areaColor="hsla(206.25, 80%, 80%, 0.01)"/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=bottom labelPosition=bottom areaColor="hsla(206.25, 80%, 80%, 0.01)"/>
    <ReferenceArea xMin='2019-07-01' xMax='2021-07-31' label=bottomRight labelPosition=bottomRight areaColor="hsla(206.25, 80%, 80%, 0.01)"/>
</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

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0 >
    <ReferenceArea xMax='2019-04-01' label=info color=info/>
    <ReferenceArea xMin='2019-04-01' xMax='2019-11-01' label=negative color=negative/>
    <ReferenceArea xMin='2019-11-01' xMax='2020-07-01' label=warning color=warning/>
    <ReferenceArea xMin='2020-07-01' xMax='2021-02-01' label=positive color=positive/>
    <ReferenceArea xMin='2021-02-01' xMax='2021-09-01' label=base-content-muted color=base-content-muted/>
    <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

color
Color to override default area and label colors
Options:
CSS name | hexademical | RGB | HSL
areaColor
Color to override default area color. If used, takes precedence over `color`
Options:
CSS name | hexademical | RGB | HSL
opacity
Opacity of the highlighted area
Options:
number
border
Renders a border around the highlighted area
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 border (in pixels)
Options:
number
labelPosition
Where label will appear within the area
Options:
Default:
topLeft
labelColor
Color to override default label 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
labelBackgroundColor
The color of the background behind the label
Options:
CSS name | hexademical | RGB | HSL
labelPadding
Padding between the text and the border of the label background
Options:
number
labelBorderWidth
The thickness of the border around the label (in pixels)
Options:
number
labelBorderRadius
The radius of rounded corners on the label background (in pixels)
Options:
number
labelBorderColor
The color of the border around the label background
Options:
CSS name | hexademical | RGB | HSL
labelBorderType
The type of border around the label background (dashed or dotted)
Options:
fontSize
The size of the font in the label
Options:
number
align
How to align the label to the symbol, and the text within the label
Options:
bold
Make the label text bold
Options:
Default:
false
italic
Make the label text italic
Options:
Default:
false

Reference Point

Reference points allow you to add labels on certain points to emphasize them in the chart. They can be produced by providing a specific x/y coordinate (e.g. x="2021-05-01" y=11012) or by providing a dataset (e.g. anomalies, points).

When a dataset is provided, ReferencePoint will generate multiple points - one for each row in the dataset. This can be helpful for plotting a large number of points with a succinct syntax.

Examples

Defined Point

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <ReferencePoint x="2019-07-01" y=6590 label="2019-07-01 : Big drop" labelPosition=bottom/>
</LineChart>

Points from Data

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <ReferencePoint data={sales_drops} x=month y=sales label=label labelPosition=bottom align=right />
</LineChart>

Custom Styling

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <ReferencePoint
        x="2019-07-01"
        y=6590
        label="2019-07-01 : Big drop"
        labelPosition=right
        color=negative
        symbolSize=16
        symbolBorderWidth=1
        symbolBorderColor=negative
        symbolOpacity=0.25
    />
</LineChart>

Label Positions

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <ReferencePoint x="2019-07-01" y=6590 label=top labelPosition=top/>
    <ReferencePoint x="2019-07-01" y=6590 label=right labelPosition=right/>
    <ReferencePoint x="2019-07-01" y=6590 label=bottom labelPosition=bottom/>
    <ReferencePoint x="2019-07-01" y=6590 label=left labelPosition=left/>
</LineChart>

Multiline label

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <ReferencePoint x="2019-07-01" y=6590 labelPosition=bottom align=left>
        A label with
        line breaks in it
        to allow longer text
    </ReferencePoint>
</LineChart>

Colours

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <ReferencePoint x="2019-03-01" y=3000 color=info label=info />
    <ReferencePoint x="2019-09-01" y=3000 color=negative label=negative />
    <ReferencePoint x="2020-03-01" y=3000 color=warning label=warning />
    <ReferencePoint x="2020-09-01" y=3000 color=positive label=positive />
    <ReferencePoint x="2021-03-01" y=3000 color=base-content-muted label=base-content-muted />
    <ReferencePoint x="2021-09-01" y=3000 color=#63178f label=custom />
</LineChart>

Options

Defining Values Inline

x
x coordinate value where the point will be plotted
Options:
number | string | date
y
y coordinate value where the point will be plotted
Options:
number | string | date
label
Required
Text to show as label for the point
Options:
string

Supplying a Dataset

data
Required
Query name, wrapped in curly braces
Options:
query name
x
Column containing x-axis values for points
Options:
column name
y
Column containing y-axis values for points
Options:
column name
label
Required
Column containing a label to use for each line
Options:
column name

Styling

color
Color to override default line and label colors
Options:
CSS name | hexademical | RGB | HSL
Default:
grey
labelColor
Color to override default label color. If used, takes precedence over `color`
Options:
CSS name | hexademical | RGB | HSL
labelWidth
The width available for the label. If text is longer than this width, it will wrap to new lines.
Options:
fit | string | number
Default:
fit
labelPadding
Padding between the text and the border of the label background
Options:
number
labelPosition
Where the label will appear relative to the point
Options:
Default:
top
labelBackgroundColor
The color of the background behind the label
Options:
CSS name | hexademical | RGB | HSL
Default:
hsla(360, 100%, 100%, 0.7)
labelBorderWidth
The thickness of the border around the label (in pixels)
Options:
number
labelBorderRadius
The radius of rounded corners on the label background (in pixels)
Options:
number
labelBorderColor
The color of the border around the label background
Options:
CSS name | hexademical | RGB | HSL
labelBorderType
The type of border around the label background (dashed or dotted)
Options:
fontSize
The size of the font in the label
Options:
number
align
How to align the label to the symbol, and the text within the label
Options:
bold
Make the label text bold
Options:
Default:
false
italic
Make the label text italic
Options:
Default:
false
symbol
The type of symbol used to mark the x/y coordinate(s)
Options:
Default:
circle
symbolColor
Color to override default symbol color. If used, takes precedence over `color`
Options:
CSS name | hexademical | RGB | HSL
symbolSize
The size of the symbol
Options:
number
Default:
8
symbolOpacity
The opacity of the symbol
Options:
number
symbolBorderWidth
The width of the border around the symbol
Options:
number
symbolBorderColor
The color of the border around the symbol
Options:
CSS name | hexademical | RGB | HSL
preserveWhitespace
When true, stops multiline labels from having whitespace at the start/end of lines trimmed
Options:
Default:
false

Callout

Callouts are very similar to reference points, just with different default styling to optimize them for slightly different use cases. Callouts allow you to add a long label somewhere on a chart to describe a trend or provide insight on the data. They can be produced by providing a specific x/y coordinate (e.g. x="2021-05-01" y=11012) or by providing a dataset (e.g. anomalies, points).

When a dataset is provided, Callout will generate multiple points - one for each row in the dataset. This can be helpful for plotting a large number of points with a succinct syntax.

Examples

Defined Point

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <Callout x="2019-07-01" y=6590 label="Sales really dropped here" labelPosition=bottom/>
</LineChart>

Points from Data

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <Callout data={sales_drops} x=month y=sales label=label labelPosition=bottom align=right />
</LineChart>

Custom Styling

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <Callout
        x="2019-07-01"
        y=6590
        label="Sales really dropped here"
        labelPosition=right
        color=negative
        symbolSize=16
        symbolBorderWidth=1
        symbolBorderColor=negative
        symbolOpacity=0.25
    />
</LineChart>

Label Positions

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <Callout x="2019-07-01" y=6590 label=top labelPosition=top/>
    <Callout x="2019-07-01" y=6590 label=right labelPosition=right/>
    <Callout x="2019-07-01" y=6590 label=bottom labelPosition=bottom/>
    <Callout x="2019-07-01" y=6590 label=left labelPosition=left/>
</LineChart>

Multiline label

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <Callout x="2019-07-01" y=6590 labelPosition=bottom align=left>
        Callout
        with
        line
        breaks
    </Callout>
</LineChart>

Colours

Loading... 
<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <Callout x="2019-03-01" y=3000 color=info label=info />
    <Callout x="2019-09-01" y=3000 color=negative label=negative />
    <Callout x="2020-03-01" y=3000 color=warning label=warning />
    <Callout x="2020-09-01" y=3000 color=positive label=positive />
    <Callout x="2021-03-01" y=3000 color=base-content-muted label=base-content-muted />
    <Callout x="2021-09-01" y=3000 color=#63178f label=custom />
</LineChart>

Options

Defining Values Inline

x
x coordinate value where the point will be plotted
Options:
number | string | date
y
y coordinate value where the point will be plotted
Options:
number | string | date
label
Required
Text to show as label for the point
Options:
string

Supplying a Dataset

data
Required
Query name, wrapped in curly braces
Options:
query name
x
Column containing x-axis values for points
Options:
column name
y
Column containing y-axis values for points
Options:
column name
label
Required
Column containing a label to use for each line
Options:
column name

Styling

color
Color to override default line and label colors
Options:
CSS name | hexademical | RGB | HSL
Default:
grey
labelColor
Color to override default label color. If used, takes precedence over `color`
Options:
CSS name | hexademical | RGB | HSL
labelWidth
The width available for the label. If text is longer than this width, it will wrap to new lines.
Options:
fit | string | number
Default:
fit
labelPadding
Padding between the text and the border of the label background
Options:
number
labelPosition
Where the label will appear relative to the point
Options:
Default:
top
labelBackgroundColor
The color of the background behind the label
Options:
CSS name | hexademical | RGB | HSL
Default:
hsla(360, 100%, 100%, 0.7)
labelBorderWidth
The thickness of the border around the label (in pixels)
Options:
number
labelBorderRadius
The radius of rounded corners on the label background (in pixels)
Options:
number
labelBorderColor
The color of the border around the label background
Options:
CSS name | hexademical | RGB | HSL
labelBorderType
The type of border around the label background (dashed or dotted)
Options:
fontSize
The size of the font in the label
Options:
number
align
How to align the label to the symbol, and the text within the label
Options:
bold
Make the label text bold
Options:
Default:
false
italic
Make the label text italic
Options:
Default:
false
symbol
The type of symbol used to mark the x/y coordinate(s)
Options:
Default:
circle
symbolColor
Color to override default symbol color. If used, takes precedence over `color`
Options:
CSS name | hexademical | RGB | HSL
symbolSize
The size of the symbol
Options:
number
Default:
8
symbolOpacity
The opacity of the symbol
Options:
number
symbolBorderWidth
The width of the border around the symbol
Options:
number
symbolBorderColor
The color of the border around the symbol
Options:
CSS name | hexademical | RGB | HSL
preserveWhitespace
When true, stops multiline labels from having whitespace at the start/end of lines trimmed
Options:
Default:
false
Edit page on GitHub