@visa/charts-types NPM

Types

A collection of common prop types used across the VCC ecosystem.

Charts that leverage these types:

Default Values

Default values for all of these types can be found the propDefaultValues file in our utils but are also outlined in the tables below.

API Contents

# Accessibility <>

# IAccessibilityType

Used by every chart. Specifies a robust set of settings that make VCC data experiences more accessible.

Description props are used to explain the chart to a user who cannot see it and should be carefully considered early in the design process. In addition, it is always best to provide explanations of the chart's context, purpose, summaries, statistics in visual, textual form for people with cognitive impairment/disability. In cases where this information is provided outside of the chart, it does not need to be provided to these props.

Note that some of these props are required by chart accessibility validation and will throw warnings until the default values are changed (such as elementsAreInterface). The prop for disableValidation should be set to true before an application's production build and deployment process but only if the chart is considered accessible (validation can slow down the chart's lifecycle performance significantly).

Name (accessibility.)	Type	Default Value(s)	Description
`longDescription`	string	''	Use this to add a helpful description of the chart.
`executiveSummary`	string	''	Use this to describe the biggest takeaway of the chart.
`purpose`	string	''	Use this to describe the purpose of this particular chart.
`contextExplanation`	string	''	Use this to explain any controls or content on your page that affect or are affected by this chart.
`title`	string	''	Gives the chart an alternate title to be used by screen readers.
`elementDescriptionAccessor`	string	''	Optional key used to add an additional description to any element, from your data.
`statisticalNotes`	string	''	Use this to provide any statistical explanations, such as trends, clusters, patterns, or outliers.
`structureNotes`	string	''	Use this to describe special visual features of the chart, such as sorting, color grouping, etc.
`includeDataKeyNames`	boolean	false	If true, includes data key names in voice over description of each element. EG "Year over year growth: 5.6%" instead of just "5.6%"
`hideDataTableButton`	boolean	false	If true, hides the data table button (but it is still available to screen reader users).
`disableValidation`	boolean	false	If true, disables validations of accessibility props for this chart. Validation is intended to be used during development; upon completion, validation should be disabled.
`elementsAreInterface`	any/boolean	null	Defaults to null. Set to true if interacting with the elements in this chart affects your application. Otherwise, must be set to false.
`onChangeFunc`	function	`undefined`	Custom event listener (changeFunc) that enables dev to control accessibility page experience when chart data updates.
`showSmallLabels`	boolean	false	Defaults to false. Set to true if you would like to display labels on small elements that are likely to overlap. Note, this could impact accessibility of your graphic.
`hideStrokes`	boolean	false	Defaults to false. Set to true if you would like to remove automated stroke outlines from the chart, note, this could impact accessibility of your graphic.
`hideTextures`	boolean	false	Defaults to false. Set to true if you would like to remove textures from the chart, note, this could impact accessibility of your graphic.
`keyboardNavConfig`	IKeyConfig	`{ disabled: false }`	Defaults disabled to false. May be set to true if `accessibility.elementsAreInterface = false` and `suppressEvents = true`. This will disable keyboard navigation and simplify chart instructions for screen reader users.
`showExperimentalTextures`	boolean	false	Defaults to false. Set to true if you would like leverage our textures which are still undergoing research and development.

# Basic Props <>

# IBoxModelType

Used by every chart for both the padding and margin props.

Name	Type	Default Value(s)	Description
`top`	number	height * 0.01	Sets the top margin/padding for the chart container.
`bottom`	number	height * 0.01	Sets the bottom margin/padding for the chart container.
`left`	number	width * 0.01	Sets the top margin/padding for the chart container.
`right`	number	width * 0.01	Sets the top margin/padding for the chart container.

# ISubTitleType

Used by every chart for to declare subtitles as a simple string, or as an object that allows certain text to be highlighted.

Name	Type	Default Value(s)	Description
`text`	string	''	Text of the subtitle.
`keywordsHighlight`	object[]	''	Data used to create highlighted words in the subtitle, an array of objects which includes `text`, `color` and `index` keys. `text` correspond to one more multiple words/numbers as a single string in the subtitle text. `color` takes a HEX color string. `index` takes a number, if not specified all occurrences of the `text` will be highlighted.

# Dumbbell Specific <>

# IBarStyleType

Dumbbell plot only. Sets props for dumbbell's bar.

Name (barStyle.)	Type	Default Value(s)	Description
`colorRule`	string	'default'	Sets the color rule for the dumbbell bar (options are 'greaterValue', 'focus' or 'default').
`opacity`	number	1	Sets the opacity of the dumbbell bar.
`width`	number	1	Sets the width of the dumbbell bar.

# IDifferenceLabelType

Dumbbell plot only. Adjusts settings for the difference label (label between dumbbell markers).

Name	Type	Default Value(s)	Description
`calculation`	string	'difference'	Sets the calculation used in the difference label. Accepts 'difference' or 'middle'.
`visible`	boolean	true	Toggles the visibility (opacity) of the difference labels.
`placement`	string	'left'	Sets the placement of the data label. Accepts 'top', 'bottom', 'left', and 'right'.
`format`	string	'0.0a'	Sets the formatting for the data labels, EG %b, refer to d3-time-format and numeral.js.

# IFocusStyleType

Dumbbell plot only. Sets props for focus marker. sizeFromBar will override marker style props, but only for markers that match the focusMarker.key.

Name (focusMarker.)	Type	Default Value(s)	Description
`key`	string	''	Key used to determine which marker to focus.
`sizeFromBar`	number	12	Sets the size of the focus marker.

# IMarkerStyleType

Dumbbell plot only. Sets props for dumbbell's markers. Focus marker's sizeFromBar will override this prop's sizeFromBar, but only for markers that match the focusMarker.key.

Name (marker.)	Type	Default Value(s)	Description
`type`	string	'dot'	Sets the shape type of dumbbell markers.
`sizeFromBar`	number	8	Sets the size of the marker.
`visible`	boolean	true	Sets the visibility of dumbbell markers.

# Interactivity <>

# IHoverStyleType

Sets the color and stroke width for elements when they match the hoverHighlight and interactionKeys props. See chart-level documentation for how to handle hover interactivity.

Name	Type	Default Value(s)	Description
`color`	string	''	Sets the color of the hovered element (requires hoverHighlight to be valid and sent).
`strokeWidth`	number	2	Sets the stroke width of the hovered element (requires hoverHighlight to be valid and sent).

# IClickStyleType

Sets the color and stroke width for elements when they match the clickHighlight and interactionKeys props. See chart-level documentation for how to handle click interactivity.

Name	Type	Default Value(s)	Description
`color`	string	''	Sets the color of the clicked element (requires clickHighlight to be valid and sent).
`strokeWidth`	number	2	Sets the stroke width of the clicked element (requires clickHighlight to be valid and sent).

# Labels and Legend <>

# IDataLabelType

Used by every chart. Specifies label values, visibility, placement, and format of data labels.

Name	Type	Default Value(s)	Description
`labelAccessor`	string	''	Key used to determine label's property.
`visible`	boolean	true	Toggles the visibility (opacity) of the data labels.
`placement`	string	'top' (vertical), 'right' (horizontal)	Sets the placement of the data label. Examples of values are 'top', 'bottom' for vertical layout and 'left', 'right', 'top-right' for horizontal layout.
`format`	string	'0.0a'	Sets the formatting for the data lables, EG %b, refer to d3-time-format and numeral.js.

# ILegendType

Specifies visibility, interactivity, format, label values, and type of chart legends. Only charts that have groupAccessor or seriesAccessor passed as the only value in interactionKeys can set interactive to true. The various styles allowed for type differ for each chart.

Name	Type	Default Value(s)	Description
`visible`	boolean	true	Toggles the visibility (opacity/display) of the legend.
`interactive`	boolean	false	Toggles the interactivity of the legend.
`format`	string	''	Sets the formatting for the legend lables, EG %b, refer to d3-time-format and numeral.js.
`labels`	string[]	''	An array that sets each label in the legend, in order. Passing empty string will populate legend labels directly from data values.
`type`	string	'bar'	Sets the type of the legend, forced to 'bar' in bar-chart.

# ISeriesLabelType

Used in Line Chart, Parallel plot, and Dumbbell plot. Specifies label content and placement for series labels.

Name	Type	Default Value(s)	Description
`label`	string[]	[]	An array which determines the labels for each line, in order.
`visible`	boolean	true	Toggles the visibility (opacity) of the series labels.
`placement`	string	'right'	Sets the placement of the series label, accepts 'left' or 'right'

# ITooltipLabelType

Used by every chart to set the label values, titles, and formatting within a tooltip.

Name	Type	Default Value(s)	Description
`labelAccessor`	string[]	[]	An array that determines which property of the data is displayed in the tooltip.
`labelTitle`	string[]	[]	An array that sets the title for each data property in the tooltip.
`format`	string	''	Sets the formatting for the data properties in the tooltip, EG %b, refer to d3-time-format and numeral.js.

# Reference Lines <>

# IReferenceStyleType

Note: The referenceLines and Style props are currently deprecated and will ultimately be fully replaced by the annotation prop. For the time being, this prop will work, but will not pass accessibility requirements. Use at your own risk or migrate to annotations.

Name	Type	Default Value(s)	Description
`color`	string	'pri_grey'	Sets the color of the reference line.
`strokeWidth`	number	1	Sets the stroke width of the reference line.
`opacity`	number	1	Sets the opacity of the reference line.
`dashed`	string	''	Sets the dash array property of the path element of the reference line.

# Secondary Lines <>

# ISecondaryLinesType

Used in Line Chart and Parallel plot. Specifies styling overrides meant to de-emphasize secondary lines (reduce cognitive load of non-essential lines). Secondary lines are matched according to strings of seriesAccessor values passed into secondaryLines.keys.

Name (secondaryLines.)	Type	Default Value(s)	Description
`keys`	string[]	[]	Assign keys of secondary lines.
`showDataLabel`	boolean	true	Sets the visibility of data labels on secondary lines.
`showSeriesLabel`	boolean	true	Sets the visibility of series labels on secondary lines.
`opacity`	number	1	Sets the opacity of secondary lines.

# World Map Specific <>

# IMapMarkerStyleType

World Map only. Adjusts the settings and style of the markers being placed on the map.

Name (markerStyle.)	Type	Default Value(s)	Description
`visible`	boolean	false	Sets the visibility of map markers.
`fill`	boolean	true	Sets whether to color markers with either a, `ordinal()` (based on groupAccessor), or `quantize()` (based on valueAccessor) color scale.
`blend`	boolean	false	Sets whether to apply mix-blend-mode multiply (true), or normal (false).
`color`	string	base_grey	Sets the color of the marker if `fill` is false.
`strokeWidth`	string	1px	Sets the stroke-width of the marker (currently requires `Npx` notation.)
`opacity`	number	0.8	Sets the opacity of the marker.
`radius`	number	5	Sets the radius of the marker, if `radiusRange` is falsy/empty string.
`radiusRange`	number[]	''	Sets the size of the marker through a value based scale, currently leverages `d3.scalePow().exponent(0.5)` for marking scaling approach.

# ICountryStyleType

World Map only. Adjusts the settings and style of the map's country features.

Name (countryStyle.)	Type	Default Value(s)	Description
`fill`	boolean	true	Sets whether to color country features with either a, `ordinal()` (based on groupAccessor), or `quantize()` (based on valueAccessor) color scale.
`opacity`	number	0.8	Sets the opacity of the country features.
`color`	string	base_grey	Sets the color of the country features if `fill` is false.
`strokeWidth`	string	1px	Sets the stroke-width of the country features (currently requires `Npx` notation.)

# X and Y Axis <>

# IAxisType

Used by most charts to customize the x and y axis. Only charts that plot dates (like Line Chart) can use the unit property. Only Parallel Plot uses yAxis.scales and yAxis.onlyTickExtents.

Name (xAxis./yAxis.)	Type	Default Value(s)	Description
`visible`	boolean	true	Toggles the visibility of the axis.
`gridVisible`	boolean	true	Toggles the visibility of the axis grid.
`label`	string	'X Axis'	Sets the label for the axis.
`placement`	string	'top' (x), 'left' (y)	Sets the axis placement for x 'top' or 'bottom' and for y 'left', or 'right'.
`format`	string	'' or '%b %y' or '0.0a'	Sets the formatting for axis elements, EG %b, refer to d3-time-format and numeral.js.
`tickInterval`	number	1	Can be used to reduce the frequency of axis ticks. This number sets the interval of axis ticks that are shown.
`unit`	string	'' or 'month'	Sets the unit of padding for the axis when accessor is a date.
`yAxis.scales`	string	`undefined` or 'preNormalized'	Sets the type of scales used in y axis for parallel plot.
`yAxis.onlyTickExtents`	boolean	true	Hides yAxis ticks between min/max for parallel plot.