Axis
The Axis component is used to display the axis, axis labels and grid marks. An axis is not required if you would like something like a sparkline visualization.
<Chart data={data}>
<Axis position="bottom" granularity="hour" grid={false} title="My Axis Title" />
</Chart>
Props
| name | type | default | description |
|---|---|---|---|
| position* | 'left' | 'bottom' | 'top' | 'right' | – | Sets where the axis will be displayed. |
| name | string | – | Sets the name of the component. |
| baseline | boolean | false | Adds a baseline rule for this axis. |
| baselineOffset | number | 0 | Adds an offset to the baseline. If baseline is false then this prop is ignored. If baseline is drawn relative to a categorical axis, this prop is ignored. |
| children | AxisAnnotation | ReferenceLine | – | Child components that add supplemental content to the axis |
| granularity | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'day' | Sets the granularity of the primary axis labels for time axis. If this axis is not for a time axis, this prop is ignored. |
| grid | boolean | false | Displays gridlines at each tick location. |
| hideDefaultLabels | boolean | false | Hides the axis labels. If labels have been explicitly added using the labels prop, these will still be visible. |
| labelAlign | 'start' | 'center' | 'end' | 'center' | Sets the alignment of axis labels. center will set the align to center for horizontal axes and the baseline to middle for vertical axes. start will set the align to left for horizontal axes and the baseline to top for vertical axes. end will set the align to right for horizontal axes and the baseline to bottom for vertical axes. |
| labelFontWeight | FontWeight | 'normal' | Sets the font weight of axis labels. |
| labelFormat | 'duration' | 'linear' | 'percentage' | 'time' | – | Sets the format of the axis labels. duration will display seconds value in a m:ss format if less than 3,600 and in a H:mm:ss format if >= 3,600 (ex: 3 = 0:03, 36 = 0:36, 366 = 6:06, 3661 = 1:01:01). |
| labelOrientation | 'horizontal' | 'vertical' | 'horizontal' | Sets the orientation of the label. If using vertical, subLabels will not be displayed. |
| labels | ({value: string | number, label?: string, align?: LabelAlign, fontWeight?: FontWeight} | number | string)[] | – | Explicitly sets the axis labels (controlled). Providing a Label object allows for more control over the label display. Either an object or the domain value (string | number) can be provided as entries to the array. Just providing the domain values makes it possible to simply control the labels that should be added without altering the display value or styling of the label. Providing an object as the label entry opens up control of the alignment, font-weight and display value of the label. fontWeight and align will default to the axis font weight and label alignment. label is equal to value by default. The following are semantically equivalent: [{value: 2, label: "2", align: 'center', fontWeight: "normal"}] = [{value: 2}] = [2] |
| tickCountLimit | number | – | Sets the upper limit on the number of axis ticks. Base tick, typically 0, is not included in the count. e.g. 0, 1, 2, 3 is considered 3 ticks. Note: The final tick count may vary based on Vega's automatic calculations to create visually pleasing values. |
| numberFormat | 'currency' | 'shortCurrency' | 'shortNumber' | 'standardNumber' | string | 'shortNumber' | Sets the format for numeric axis labels. This format must be a d3-format specifier (Example: '$.2f' = $5,432.10). Number locale will be applied to the number format. The following presets are also provided: currency ($2.50), shortCurrency ($20M), shortNumber (3B), standardNumber (2,500). Only valid if labelFormat is linear or undefined. |
| range | [number, number] | – | The minimum and maximum values for the axis, for example: [-10, 10]. Note: This prop is only supported for axes with linear or time scale types. |
| subLabels | {value: string | number, subLabel: string, align?: LabelAlign, fontWeight?: FontWeight}[] | – | Adds sublabels below the axis labels. If the provided value is not within the axis domain, it won't be added. Note that if labelOrientation is set to vertical, subLabels will not be displayed. |
| ticks | boolean | false | Displays ticks at each label location. |
| tickMinStep | number | – | The minimum desired step between axis ticks, in terms of scale domain values. For example, a value of 1 indicates that ticks should not be less than 1 unit apart. Note: This prop is only supported for linear axes. |
| title | string | string[] | – | Sets the axis title. If an array of strings is provided, each string will render on a new line. |
| truncateLabels | boolean | false | If the text is wider than the bandwidth that is labels, it will be truncated so that it stays within that bandwidth. This is only valid for categorical axes (ex. dimension axis on a bar chart). This setting is also ignored if the labels prop is used to control the axis labels. |
| currencyLocale | string | – | Set the locale for currency formatting (affects symbol position and spacing). ⚠️ Limited Support: Support for and changes to this prop will be limited. Only use this if you need to override the currency locale formatting from the chart locale. Important: This prop requires 'currencyCode' prop to take effect. Example: 'en-US' ($100) vs 'de-DE' (100 $) |
| currencyCode | string | – | Override the currency symbol from the chart locale with a specific currency code. ⚠️ Limited Support: Support for and changes to this prop will be limited. Only use this if you need to override the currency symbol from the chart locale. Important: This prop requires 'currencyLocale' prop to take effect. |
Content
The Axis component supports additional content as children.
AxisAnnotation
An AxisAnnotation can be used to add icons to an axis. These are typically used to provide information in a tooltip or popover for a specific data point or range.
Example
const axisAnnotationProps = {
dataKey: 'annotations',
color: 'gray-600',
}
<Chart data={data}>
<Axis position="bottom" granularity="hour" grid={false} title="My Axis Title">
<AxisAnnotation {...axisAnnotationProps} />
</Axis>
</Chart>
// Todo axisannotation image
AxisAnnotation Props
| name | type | default | description |
|---|---|---|---|
| children* | ChartPopover | ChartTooltip | - | Optional content of the AxisAnnotation |
| color | Color | string | 'gray-600' | The color to use for the annotation icons and range lines if a color isn't specified in options, or multiple annotations fall in the same icon. CSS color names and spectrum color names are supported. |
| dataKey | string | 'annotations' | The data field where the annotation ids are listed for each data point. |
| format | 'span' | 'summary' | 'span' if using a time based scale, otherwise 'summary' | Show annotations as a horizontal span of icons or a single summary icon. |
| name | string | A generated string that includes the axis name and the index of the annotation. | Unique name for the annotation to be used as an identifier. |
| offset | number | 80 | Adds pixels to offset the annotation from the bottom of the bottom of the chart. |
| options | { id: string, color: Color | string }[] | [] | Options specific to each annotation in the data. |
AxisAnnotation Options
An array of option objects can be passed to the prop options to control individual annotations using an id.
| name | type | default | description |
|---|---|---|---|
| id | string | - | The id of the annotation to apply the options to. |
| color | Color | string | - | The color of the annotation icon and range lines. CSS color names and spectrum color names are supported. |
const axisAnnotationProps = {
dataKey: 'annotations',
options: [
{ id: '1', color: 'magenta-600' },
{ id: '2', color: 'fuchsia-600' },
{ id: '3', color: 'yellow-600' },
{ id: '4', color: 'celery-600' },
],
}
<Chart data={data}>
<Axis position="bottom" granularity="hour" grid={false} title="My Axis Title">
<AxisAnnotation {...axisAnnotationProps} />
</Axis>
</Chart>
ReferenceLine
A ReferenceLine can be used to add a vertical or horizontal line to a chart as a reference.
<Chart data={data}>
<Axis position="bottom" granularity="hour" grid={false} title="My Axis Title">
<ReferenceLine value={0.5} icon="date" />
</Axis>
</Chart>
//todo add reference line image
ReferenceLine Props
| name | type | default | description |
|---|---|---|---|
| value* | number | string | – | Sets the value on the axis that the reference line will be drawn at. |
| color | SpectrumColor | string | 'gray-800' | Sets the color of the reference line. |
| icon | SupportedIcon | string (svg path) | – | Adds an icon on the axis for the reference line. Either the name of a supported svg icon can be provided or an svg path string can be provided. For correct sizing, custom svg paths should be defined within a square bounding box with coordinates ranging from -1 to 1 along both the x and y dimensions. |
| iconColor | SpectrumColor | string | 'gray-800' | Sets the color of the icon. |
| label | string | – | Adds a text label on the axis for the reference line. This will be positioned outside of the icon if both an icon and a label are provided (e.g., beneath the icon if the axis position is bottom, left of the icon if the axis position is left). |
| labelColor | SpectrumColor | string | 'gray-800' | Sets the color of the label. |
| labelFontWeight | string | 'normal' | Sets the font weight of the label. |
| layer | 'back' | 'front' | 'front' | Sets the layer that the reference line gets drawn on. If set to back, the reference line will be drawn behind all data marks (bars, lines, etc.). If front, the reference line will be drawn in front of all data marks. |
| position | 'before' | 'after' | 'center' | 'center' | Set the reference line position to either center on the value, or to be between the value and the value before or after. Typically used in Bar visualizations where spacing is more likely to exist between values. |
Icons
An icon can be used as a label for the reference line. Either the name of a supported svg icon can be provided or an svg path string can be provided. For correct sizing, custom svg paths should be defined within a square bounding box with coordinates ranging from -1 to 1 along both the x and y dimensions.
Supported Icons:
- date
If there is a Spectrum Icon that is not supported, submit an issue to this repo to get it added.