@visa/line-chart
npm i @visa/line-chart

@visa/line-chart

Visa Chart Components (VCC) is an accessibility focused, framework agnostic set of data experience design systems components for the web. VCC attempts to provide a toolset to enable developers to build equal data experiences for everyone, everywhere.

by visa

5.1.1 (see all)License:SEE LICENCE IN LICENSETypeScript:Built-In
npm i @visa/line-chart
Readme

@visa/line-chart

An image depicting an example of the default line-chart component

<line-chart
  accessibility = {...}
  data = {[{"date":"2016-01-01T00:00:00.000Z","category":"Restaurant","value":120},{data}]}
  valueAccessor = {"value"}
  ordinalAccessor = {"date"}
  seriesAccessor = {"category"}
/>

Jump To:
  1. Installation Steps
  2. Props Documentation

# Installation Steps


  • Using npm

    $ npm i @visa/line-chart
    
  • Using yarn

    $ yarn add @visa/line-chart
    

# Props Documentation



# Base Props <>

NameTypeDefault Value(s)Description
heightnumber300Height in px of the chart container
widthnumber650Width in px of the chart container
mainTitlestring'Line Chart Title'The dynamic tag of title for the chart (or you can create your own separately). See highestHeadingLevel prop for how tags get assigned.
subTitlestring'This is the line chart's subtitle'The dynamic tag for a sub title for the chart (or you can create your own separately). See highestHeadingLevel prop for how tags get assigned.
highestHeadingLevelstring/number'h2'Sets the heading level (which also sets sublevels) for the chart. "p", "span", and "div" are also valid.


# Data Props <>

NameTypeDefault Value(s)Description
ordinalAccessorstring'label'Key used to determine line's categorical property.
valueAccessorstring'value'Key used to determine line's numeric property. Note: see Line interpolation behavior below for further details on behavior of lines based on valueAccessor data passed.
seriesAccessorstring'series'Key used to determine series.
uniqueIDstringundefinedID used to identify chart (must be unique per chart), helpful for validation messages. Defaults to UUID v4 standard.
dataobject[]undefinedData used to create chart, an array of objects which includes keys that map to above accessors.
secondaryLinesobject (custom type)ISecondaryTypeArray of values used to classify series as secondary

ISecondaryType Definition

Name (secondaryLines.)TypeDefault Value(s)Description
keysstring[][]Assign keys of secondary lines.
showDataLabelbooleantrueSets the visibility of data labels on secondary lines.
showSeriesLabelbooleantrueSets the visibility of series labels on secondary lines.
opacitynumber1Sets the opacity of secondary lines.

Line interpolation behavior

The way data is sent to line-chart will have significant impacts on how the component will render lines. Here are three main scenarios you can take advantage of to ensure lines are rendered as need be for your use case.

ScenarioDescriptionExpected Result
All values present and passed to chartThe data object array passed has a valid numeric value or valueAccessor for each ordinalAccessor, and seriesAccessor value.An image depicting an example of the default line-chart component
Each point on line is rendered.
Missing values *not* passed to chartThe data object array passed has a valid numeric value or valueAccessor for some ordinalAccessor, and seriesAccessor values. E.g., null valueAccessor values are filtered, before sending data object to chart.An example of the default line-chart component, with lines connecting over data not send to chart.
Lines will connect/interpolate over data which is not sent to chart.
Missing values *are* passed to chartThe data object array passed has a valid numeric value or valueAccessor for some ordinalAccessor, and seriesAccessor values. Also, null or undefined values are passed for any missing data. E.g., null valueAccessor values are included when sending data object to chart.An example of the default line-chart component, with lines breaking when null values of data are send to chart.
Lines will break to reflect the null or undefined data passed.


# Accessibility Props <>

NameTypeDefault Value(s)Description
accessibilityobject (custom type)IAccessibilityTypeManages messages and settings for chart accessibility, see object definition below.

IAccessibilityType Definition

Name (accessibility.)TypeDefault Value(s)Description
longDescriptionstring''Use this to add a helpful description of the chart.
executiveSummarystring''Use this to describe the biggest takeaway of the chart.
purposestring''Use this to describe the purpose of this particular chart.
contextExplanationstring''Use this to explain any controls or content on your page that affect or are affected by this chart.
titlestring''Gives the chart an alternate title to be used by screen readers.
elementDescriptionAccessorstring''Optional key used to add an additional description to any element, from your data.
statisticalNotesstring''Use this to provide any statistical explanations, such as trends, clusters, patterns, or outliers.
structureNotesstring''Use this to describe special visual features of the chart, such as sorting, color grouping, etc.
includeDataKeyNamesbooleanfalseIf true, includes data key names in voice over description of each element. EG "Year over year growth: 5.6%" instead of just "5.6%"
hideDataTableButtonbooleanfalseIf true, hides the data table button (but it is still available to screen reader users).
disableValidationbooleanfalseIf true, disables validations of accessibility props for this chart. Validation is intended to be used during development; upon completion, validation should be disabled.
elementsAreInterfaceany/booleannullDefaults to null. Set to true if interacting with the elements in this chart affects your application. Otherwise, must be set to false.
onChangeFuncfunctionundefinedCustom event listener (changeFunc) that enables dev to control accessibility page experience when chart data updates.
showSmallLabelsbooleanfalseDefaults 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.
hideStrokesbooleanfalseDefaults 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.
hideTexturesbooleanfalseDefaults to false. Set to true if you would like to remove textures from the chart, note, this could impact accessibility of your graphic.
keyboardNavConfigIKeyConfig{ 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.
showExperimentalTexturesbooleanfalseDefaults to false. Set to true if you would like leverage our textures which are still undergoing research and development.

// accessibility = { ...accessibility, onChangeFunc: d => changeHandler(d)}
// example of setting updates on page based on changeFunc custom events
const changeHandler = d => {
  if (d.updated && (d.removed || d.added)) {
    let updates = 'The line chart has ';
    if (d.removed) {
      updates += 'removed ' + d.removed + ' point' + (d.removed > 1 ? 's ' : ' ');
    }
    if (d.added) {
      updates += (d.removed ? 'and ' : '') + 'added ' + d.added + (d.removed ? '' : d.added > 1 ? ' points' : ' point');
    }
    setChartUpdates(updates);
  } else if (d.updated) {
    const newUpdate = "The chart's data has changed, but no points were removed or added.";
    setChartUpdates(
      newUpdate !== chartUpdates
        ? newUpdate
        : "The chart's data has changed again, but no data points were removed or added."
    );
  }
};


# Annotation Props <>

NameTypeDefault Value(s)Description
annotationsarray[{annotations}][]Adds annotations to the chart, see d3-svg-annotation by Susie Lu.

annotations object definition

annotations is an array of objects which needs to have the following properties within them. See the detailed api specifications from d3-svg-annotation, along with additional properties layered on top of that work, documented below.

NameTypeDefault Value(s)Description
accessibilityDescriptionstringundefinedSets the accessibility description for the annotation for screen reader users.


# Axis Props <>

NameTypeDefault Value(s)Description
xAxisobject (custom type)IAxisTypeManages settings for the chart's x axis, see object definition below.
yAxisobject (custom type)IAxisTypeManages settings for the chart's y axis, see object definition below.
minValueOverridenumberundefinedOverrides the calculated default min value.
maxValueOverridenumberundefinedOverrides the calculated default max value.
showBaselineXbooleanfalseWhen selected, shows the x baseline
wrapLabelbooleantrueWhen selected, wraps axis labels.

IAxisType Definition

Name (xAxis./yAxis.)TypeDefault Value(s)Description
visiblebooleantrueToggles the visibility of the axis.
gridVisiblebooleantrueToggles the visibility of the axis grid.
labelstring'X Axis'Sets the label for the axis.
unitstring'' or 'month'Sets the unit of padding for the axis when accessor is a date.
formatstring'' or '%b %y' or '0[.][0][0]a'Sets the formatting for axis elements, EG %b, refer to d3-time-format and numeral.js.
tickIntervalnumber1Can be used to reduce the frequency of axis ticks. This number sets the interval of axis ticks that are shown.


# Event Props <>

Events in stencil.js dispatch Custom DOM events for other components to handle, we use Stencil's @Event() decorator to emit events (click, hover, mouseOut) from end user activity on our charts.

NameTypeDefault Value(s)Description
suppressEventsbooleanfalseSuppresses and disables click, hover and mouseOut event emitters. Setting to true can increase performance for non-interactive charts.
cursorstring'default'Changes pointer type during mouse over on elements. Valid values are 'default' or 'pointer'.
onClickEventfunctionundefinedWhen clickEvent event occurs (e.g., mouse/keyboard click on chart geometry), this event handler will be called with the custom event object (e.g., e), containing data and target node at e.detail {data: d, target: n}. You will need to construct your own functionality of what actions to take within the callback.
clickHighlightobject[][]Data used to track chart selections, an array of objects which includes keys that map to above accessors.
clickStyleobject (custom type)IClickStyleTypeSets the styling of elements when they are selected, see object definition below.
onHoverEventfunctionundefinedWhen hoverEvent event occurs (e.g., mouse hover/keyboard focus on chart geometry), this event handler will be called with the custom event object (e.g., e), containing data and target node at e.detail {data: d, target: n}. You will need to construct your own functionality of what actions to take within the callback.
onMouseOutEventfunctionundefinedWhen mouseOutEvent event occurs (e.g., mouse/keyboard blur on chart geometry), this event handler will be called, and has no data object. You will need to construct your own functionality of what actions to take within the callback.
hoverHighlightobject{}Datum object used to track active chart element, the object should include keys that map to above accessors.
hoverStyleobject (custom type)IHoverStyleTypeSets the styling of elements when they are hovered/focused, see object definition below.
interactionKeysstring[][]Sets the column names of data to interact with.
hoverOpacitynumber1Sets opacity of inactive elements when hovering/focused on a chart geometry.
onInitialLoadEventfunctionundefinedWhen initalLoad event occurs (e.g., chart is mounted to window), this event handler will be called with the custom event object (e.g., e), containing the corresponding chartID at e.detail. You will need to construct your own functionality of what actions to take within the callback.
onDrawStartEventfunctionundefinedWhen drawStart event occurs (e.g., chart render function is called), this event handler will be called with the custom event object (e.g., e), containing the corresponding chartID at e.detail. You will need to construct your own functionality of what actions to take within the callback.
onDrawEndEventfunctionundefinedWhen drawEnd event occurs (e.g., chart's stencil lifecycle completes), this event handler will be called with the custom event object (e.g., e), containing the corresponding chartID at e.detail. You will need to construct your own functionality of what actions to take within the callback.
onTransitionEndEventfunctionundefinedWhen transitionEnd event occurs (e.g., chart geometry's transition lifecycle completes), this event handler will be called with the custom event object (e.g., e), containing the corresponding chartID at e.detail. You will need to construct your own functionality of what actions to take within the callback.

IClickStyleType Definition

NameTypeDefault Value(s)Description
colorstring''Sets the color of the clicked element (requires clickHighlight to be valid and sent).
strokeWidthnumber2Sets the stroke width of the clicked element (requires clickHighlight to be valid and sent).

IHoverStyleType Definition

NameTypeDefault Value(s)Description
colorstring''Sets the color of the hovered element (requires hoverHighlight to be valid and sent).
strokeWidthnumber2Sets the stroke width of the hovered element (requires hoverHighlight to be valid and sent).
// example of interactivity code
// note this only tracks a single click, you need your own logic to build the array of currnet selections made by user and then pass that result back to chart
//...
const clickHandler = evt => {
  const d = evt.detail.data; // data is located here
  const t = evt.detail.target; // chart mark/label clicked is located here

  this.currentClickedElement = [d]; // this is passed to clickHighlight prop
};

const hoverHandler = evt => {
  const d = evt.detail.data; // data is located here
  const t = evt.detail.target; // chart mark/label clicked is located here

  this.currentHoveredElement = d; // this is passed to hoverHighlight prop
};

const mouseOutHandler = evt => {
  this.currentHoveredElement = ''; // this is passed to hoverHighlight prop
};

// an example of calling these from within a stencil.js component
<line-chart
  data={[{ data }]}
  valueAccessor={'value'}
  ordinalAccessor={'date'}
  seriesAccessor={'category'}
  interactionKeys={['category']}
  onClickEvent={this.onClickEvent}
  clickHighlight={this.currentClickedElement}
  clickStyle={this.clickStyle}
  onHoverEvent={this.onHoverEvent}
  onMouseOutEvent={this.onMouseOut}
  hoverHighlight={this.currentHoveredElement}
  hoverStyle={this.hoverStyle}
/>;
//...


# Label Props <>

NameTypeDefault Value(s)Description
dataLabelobject (custom type)IDataLabelTypeControls visibility, styling and placement of data labels, see object definition below.
seriesLabelobject (custom type)ISeriesLabelTypeControls visibility, styling and placement of series labels, see object definition below.
legendobject (custom type)ILegendTypeControls visibility and label of the chart legend, see object definition below.
showTooltipbooleantrueToggles whether to display the tooltip on hover/focus on chart geometries.
tooltipLabelobject (custom type)ITooltipLabelTypeControls visibility, content and format of the chart tooltip, see object definition below.

IDataLabelType Definition

NameTypeDefault Value(s)Description
labelAccessorstring''Key used to determine label's property.
visiblebooleantrueToggles the visibility (opacity) of the data labels.
placementstring'top'Sets the placement of the data label, accepts 'top' or 'bottom'. Placement option 'auto' leverages the resolveLabelCollision algorithm and places labels without overlaps in available space on the chart.
formatstring'0[.][0][0]a'Sets the formatting for the data labels, EG %b, refer to d3-time-format and numeral.js.
collisionHideOnlybooleanfalseToggles whether to run resolveLabelCollision algorithm and hide labels if collision is detected (vs hide and then place). This is overridden by placement being set to auto.
collisionPlacementstring'all'Sets the placement of the data label when resolveLabelCollision algorithm is run (dataLabel.placement must be 'auto'). Examples of values are 'all', 'top', 'middle', 'bottom', 'left' and 'right'.

ISeriesLabel Definition

NameTypeDefault Value(s)Description
labelstring[][]An array which determines the labels for each line, in order.
visiblebooleantrueToggles the visibility (opacity) of the series labels.
placementstring'right'Sets the placement of the series label, accepts 'left' or 'right'. Placement option 'auto' leverages the resolveLabelCollision algorithm and places labels without overlaps in available space on the chart.
collisionHideOnlybooleanfalseToggles whether to run resolveLabelCollision algorithm and hide series labels if collision is detected (vs hide and then place). This is overridden by placement being set to auto.

ILegendType Definition

NameTypeDefault Value(s)Description
visiblebooleantrueToggles the visibility (opacity/display) of the legend.
interactivebooleanfalseToggles the interactivity of the legend.
formatstring''Sets the formatting for the legend labels, EG %b, refer to d3-time-format and numeral.js.
labelsstring[]''An array that sets each label in the legend, in order. Passing empty string will populate legend labels directly from data values.

ITooltipLabelType Definition

NameTypeDefault Value(s)Description
labelAccessorstring[][]An array that determines which property of the data is displayed in the tooltip.
labelTitlestring[][]An array that sets the title for each data property in the tooltip.
formatstring''Sets the formatting for the data properties in the tooltip, EG %b, refer to d3-time-format and numeral.js.


# Margin & Padding Props <>

NameTypeDefault Value(s)Description
marginobject (custom type)IBoxModelTypeMargin between the subtitle and the chart area, or between the title and chart area if no subtitle is specified, see object definition below.
paddingobject (custom type)IBoxModelTypePadding between plot area and axes lines, see object definition below.

IBoxModelType Definition

NameTypeDefault Value(s)Description
topnumberheight * 0.01Sets the top margin/padding for the chart container.
bottomnumberheight * 0.01Sets the bottom margin/padding for the chart container.
leftnumberwidth * 0.01Sets the top margin/padding for the chart container.
rightnumberwidth * 0.01Sets the top margin/padding for the chart container.


# Style Props <>

NameTypeDefault Value(s)Description
colorPalettestring'diverging_RtoB'Included color palettes can be found in our color utility. Overridden by colors.
colorsstring[]undefinedAccepts array of color strings or color values to customize colors beyond our palettes Colors assigned in order.
dotRadiusnumber4Sets the radius of data points, if visible.
showDotsbooleantrueWhen selected, makes data point dots visible.
strokeWidthstring'2'Changes stroke width of series lines.


# Reference Line Props Deprecated<>

The referenceLines and referenceStyle props are currently deprecated and will ultimately be fully replaced with the annotation prop. For the time being, this prop will work, but will also not pass accessibility requirements.

NameTypeDefault Value(s)Description
referenceLinesobject[][]Data that sets the location and labeling of the reference line
referenceStyleobject (custom type)IReferenceStyleTypeSets the styling of reference line(s) placed on the chart, see object definition below. ### IReferenceStyleType Definition

IReferenceStyleType Definition

NameTypeDefault Value(s)Description
colorstring'pri_grey'Sets the color of the reference line.
strokeWidthnumber1Sets the stroke width of the reference line.
opacitynumber1Sets the opacity of the reference line.
dashedstring''Sets the dash array property of the path element of the reference line.

referenceLines object definition

referenceLines is an array of objects which needs to have the following properties within them.

NameTypeDefault Value(s)Description
labelstringundefinedSets the label to show for the reference line.
labelPlacementHorizontalstringundefinedSets the horizontal label placement for the reference line.
labelPlacementVerticalstringundefinedSets the vertical label placement for the reference line.
valuenumberundefinedSets the value where to place the reference line, per the axis.

Downloads/wk

1

GitHub Stars

89

LAST COMMIT

3mos ago

MAINTAINERS

2

CONTRIBUTORS

5

OPEN ISSUES

1

OPEN PRs

0
VersionTagPublished
5.1.1
latest
3d ago
No alternatives found
No tutorials found
Add a tutorial