Svelte Tiny Linked Charts

This is a library to display tiny bar charts. These charts are more so meant for graphic aids, rather than scientific representations. There's no axis labels, no extensive data visualisation, just bars.

Inspired by steamcharts.com

GitHub

Demo

Name	30 day period	Value
A thing		2,120
Another thing		2,315
A third thing		2,123
An incomplete thing		1,067
A changing thing		2,243
A varying thing		1,713
A thing using lines		2,117

Installation

Install using Yarn or NPM.

yarn add svelte-tiny-linked-charts npm install --save svelte-tiny-linked-charts

If you are using Svelte 4, use version ^1.0.0. Version 2 and above is reserved for Svelte 5. The props between Svelte 4 and 5 are almost the same, but there are some breaking changes.

Include the chart in your app.

<LinkedChart {data} />

import { 
  LinkedChart, 
  LinkedLabel, 
  LinkedValue 
} from "svelte-tiny-linked-charts"

Supply your data in a simple key:value object:

let data = { 
   "2005-01-01": 25, 
   "2005-01-02": 20, 
   "2005-01-03": 18, 
   "2005-01-04": 17, 
   "2005-01-05": 21 
 }

<LinkedChart {data} />

Or if you prefer supply the labels and values separately:

let labels = [ 
   "2005-01-01", 
   "2005-01-02", 
   "2005-01-03", 
   "2005-01-04", 
   "2005-01-05" 
 ]

let values = [ 
   25, 
   20, 
   18, 
   17, 
   21 
 ]

<LinkedChart {labels} {values} />

Usage

The chart in it's most basic form. <LinkedChart {data} />

You can link multiple charts together, hovering one will also highlight others.

<LinkedChart {data} linked="link-1" /> 
 <LinkedChart {data} linked="link-1" /> 
 <LinkedChart {data} linked="link-1" /> 
 <LinkedChart {data} linked="link-1" />

The highest value in the chart is automatically determined by the highest value in your data. To overwrite this use "scaleMax".

<LinkedChart {data} scaleMax={100} /> 
 <LinkedChart {data} scaleMax={100} />

In some cases you might be working with very precise values in a specific range. By default the bar will always scale from 0. This can be overwritten using "scaleMin".

<LinkedChart {data} scaleMin={30} scaleMax={31} /> 
 <LinkedChart {data} scaleMin={5000} scaleMax={5010} />

Label

You can optionally display a label, which will display the label of what you're currently hovering.

<LinkedLabel linked="link-2" /> 
 
 <LinkedChart {data} linked="link-2" /> 
 <LinkedChart {data} linked="link-2" />

The label has no styling by default.

Start hovering

You can enable the value you're hovering using "showValue". <LinkedChart {data} showValue />
This can be further enhanced with "valueDefault", "valuePrepend", and "valueAppend".

<LinkedChart 
   {data} 
   showValue 
   valueDefault="Empty label" 
   valuePrepend="Thing:" 
   valueAppend="views" />

This value has no styling by default.

Thing: 0 views

The value can be positioned at the location of the hovered bar using "valuePosition".

<LinkedChart 
   {data} 
   showValue 
   valuePosition="floating" />

You're expected to style this value further yourself.

Alternatively you can show the value as a separate element wherever you like using the "LinkedValue" component. Use "uid" to link the chart and value together.

<LinkedChart {data} uid="some-id" /> 
 <LinkedValue uid="some-id" />

This value has no styling by default.

Separate value

The value can be transformed in order to append, prepend, or otherwise format the value. This is done using the transform prop.

<LinkedValue
   uid="some-id"
   transform={(value) => value.toLocaleString() + "%"} />

Styling

The width of the bars is fixed by default, but can be set to grow to fill the chart. <LinkedChart data={...} grow />

To change the size of the bars set the "barMinWidth" property.

<LinkedChart data={...} barMinWidth={2} /> 
 <LinkedChart data={...} barMinWidth={14} />

A minimum height can be set using the "barMinHeight" property. Bars will never be lower than this value, even if it's zero.

<LinkedChart data={...} barMinHeight={0} /> 
 <LinkedChart data={...} barMinHeight={5} />

In some cases you may want to hide bars below a certain number. An empty space will be shown instead. For this we can use "hideBarBelow". We can use this in combination with "barMinHeight" to make sure tiny numbers still render, but 0 is not shown.

<LinkedChart
   data={...}
   barMinHeight={2}
   hideBarBelow={1} />

To always fill out the content, giving the bars a dynamic width, you can set both the "grow" and "barMinWidth" properties.

<LinkedChart
   data={...} 
   grow 
   barMinWidth={0} />

The charts can be resized to any size you like. It renders as an SVG, so they can easily be made responsive with some CSS.

<LinkedChart
   data={...} 
   width={250} 
   height={100} />

svg { 
   width: 100%; 
   height: auto; 
 }

or for a fixed height;

svg { 
   width: 100%; 
   height: 50px; 
 }

The gap in between bars can also be adjusted.

<LinkedChart {data} gap={10} /> 
 <LinkedChart {data} gap={0} />

When the bars do not fill the width of the graph they are aligned to the right by default. This can be set to be left aligned instead. <LinkedChart {data} align="left" />

The bars can be colored any way you wish.

<LinkedChart fill="#ff00ff" /> 
 <LinkedChart fill="rgb(255, 255, 0)" /> 
 <LinkedChart fill="hsla(290, 55%, 50%, 1)" />

(From version 2.1.0)
An array can be passed to color each bar individually. This supports the same values as the fill property above. Bars will be filled matching the index of the bar, falling back to the given fill when not given. For instance; In an array of [null, "red"], all items will use the given fill color, except for the second bar.

<LinkedChart fillArray={data.map(i => i > 40 ? "green" : "red")} /> 
 <LinkedChart fillArray={data.map(i => `hsl(${i * 10}, 55%, 50%)`)} />

The opacity of faded out bars can be adjusted using "fadeOpacity". <LinkedChart {data} fadeOpacity={0.15} />

The hover effect can be disabled altogether using "hover". <LinkedChart {data} hover={false} />

Bars can be set to transition between states.
Value is speed in milliseconds. <LinkedChart {data} transition={500} />

Instead of bars you can also opt for a line-chart using "type=line". "lineColor" can be used to color the line, "fill" to color the points. This can have all of the bar properties as well.

<LinkedChart {data} type="line" /> 
 <LinkedChart 
   {data} 
   type="line" 
   lineColor="#4355db" 
   fill="var(--text-color)" />

Accessibility

To improve accessibility you can set tabindex=0, allowing navigating to each data point using the keyboard. When this is passed, each bar will have a title element describing it's label and value (e.g. 2005-04-12: 76).

<LinkedChart {data} tabindex="0" />

(From version 2.2.0)
Additionally, you can provide a title and description. Both are used to describe the chart. When the chart is interactive, you should consider explaining the interaction in the description.

<LinkedChart {data} title="Monthly things chart" />

<LinkedChart {data} description="A bar chart showing monthly things; A varying trend is shown with data points for each day." />

Providing a title and description is crucial for all users to be able to understand your chart when using tabindex=0.

Events

Several events are available to use the chart data on various user interactions or updates.

<LinkedChart 
   onhover={(options) => console.log(options)} 
   onblur={(options) => console.log(options)} 
   onvalueupdate={(options) => console.log(options)} />

This could be used to construct your own value element that can be formatted as you wish. For example in this example the values are given as cents, but the value is formatted as dollars.

<LinkedChart 
   onhover={({ value }) => { 
    	const element = document.querySelector("[data-role='currency']") 
 
     element.innerHTML = (value || 0 / 100).toLocaleString("en-US", { 
       style: "currency", currency: "USD"
     }) 
   }} 
   onblur={() => document.querySelector("[data-role='currency']").innerHTML = " "} />
 
 <span data-role="currency"></span>

In this example we format the value element inside the chart directly to make use of "toLocaleString()" to format the number. Ideally you would supply the value already formatted to avoid having to do this, but that's not always possible.

Value: 0

<LinkedChart 
   showValue 
   valuePosition="floating" 
   valuePrepend="Value: " 
   onvalueupdate={({ valueElement, value }) => { 
    if (valueElement) valueElement.innerText = (value || 0).toLocaleString() 
   }} />

All events

Property Description Return onhover

On hover of bars

uid, key, index, linkedKey, value, valueElement, eventElement onblur

On blur of the chart

uid, linkedKey, valueElement, eventElement onvalueupdate

Any time the value updates

value, uid, linkedKey, valueElement

Properties

This is a list of all configurable properties on the "LinkedChart" component.

Property Default Description data {}

Data that will be displayed in the chart supplied in key:value object.

labels []

Labels supplied separately, to be used together with "values" property.

values []

Values supplied separately, to be used together with "labels" property.

linked

Key to link this chart to other charts with the same key.

uid

Unique ID to link this chart to a LinkedValue component with the same uid.

height 40

Height of the chart in pixels.

width 150

Width of the chart in pixels.

barMinWidth 4

Width of the bars in the chart in pixels.

barMinHeight 0

Minimum height of the bars in the chart in pixels.

hideBarBelow 0

Bars below this value will be hidden, showing as 0 height.

grow false

Whether or not the bar should grow to fill out the full width of the chart.

align right

The side the bars should align to when they do not completely fill out the chart.

gap 1

Gap between the bars in pixels.

fill #ff3e00

Color of the bars, can be any valid CSS color.

fillArray []

Array of colors for each individual bar.

fadeOpacity 0.5

The opacity the faded out bars should display in.

hover true

Boolean whether or not this chart can be hovered at all.

transition 0

Transition the chart between different stats. Value is time in milliseconds.

showValue false

Boolean whether or not a value will be shown.

valueDefault " "

Default value when not hovering.

valueUndefined 0

For when the hovering value returns undefined.

valuePrepend

String to prepend the value.

valueAppend

String to append to the value.

valuePosition static

Can be set to "floating" to follow the position of the hover.

scaleMax 0

Use this to overwrite the automatic scale set to the highest value in your array.

scaleMax 0

Use this to overwrite the default value floor of 0.

type bar

Can be set to "line" to display a line chart instead.

lineColor fill

Color of the line if used with type="line".

preserveAspectRatio false

Sets whether or not the SVG will preserve it's aspect ratio.

tabindex -1

Sets the tabindex of each bar. When a tabindex of 0 is given, each bar will contain a title that describes the bar's label and value.

title ""

Title that describes the chart for screen readers.

description ""

Description that describes the chart for screen readers.

onclick () => null

Function that executes on click and returns the key and index for the clicked data.

onhover () => null

Function that executes on hover of each bar.

onblur () => null

Function that executes when focus leaves the chart.

onvalueupdate () => null

Function that executes when a value in the chart updates.

This is a list of all configurable properties on the "LinkedLabel" component.

Property Default Description linked

Key to link this label to charts with the same key.

empty  

String that will be displayed when no bar is being hovered.

transform (label) => label

Transform the given label to format it differently from how it was supplied.

This is a list of all configurable properties on the "LinkedValue" component.

Property Default Description uid

Unique ID to link this value to a chart with the same uid.