Charts

The "Charts" component is an extra component which let you draw charts easily.

To create and draw the charts, this project is using D3js.

Table of contents

Showcase

The following examples are the one provided in the src/index.html of this component. If you would like to run them locally, proceed as follow:

git clone https://github.com/deckgo/deckdeckgo cd webcomponents/charts npm install npm run start

Pie

Donut

Animated pie

Compare two graphs

Line and area

Compare two lines and smoothing effect

Compare two lines and display a grid

Animated lines

Bar

Compare multiple bars

Animated bars

Video

Have a look at this video where we demonstrate it!

Installation

This component could be added to your web application using the following methods.

If you are using our Starter Kit this template is included. You don't need to install it so therefore you should skip the "Installation" chapter.

Using DeckDeckGo charts from a CDN

It's recommended to use unpkg to use the DeckDeckGo charts from a CDN. To do so, add the following include script in the main HTML file of your project:

<script type="module" src="https://unpkg.com/@deckdeckgo/charts@latest/dist/deckdeckgo-charts/deckdeckgo-charts.esm.js"></script> <script nomodule="" src="https://unpkg.com/@deckdeckgo/charts@latest/dist/deckdeckgo-charts/deckdeckgo-charts.js"></script>

Install DeckDeckGo charts from NPM

Install DeckDeckGo charts in your project from npm using the following command:

npm install @deckdeckgo/charts

Framework integration

The Stencil documentation provide examples of framework integration for Angular, React, Vue and Ember.

That being said, commonly, you might either import or load it:

Import

import '@deckdeckgo/charts';

Loader

import { defineCustomElements as deckDeckGoElement } from '@deckdeckgo/charts/dist/loader'; deckDeckGoElement();

Usage

The main idea behind the DeckDeckGo charts is to be able to drop a csv file, provide it to the component and let it do the job respectively draw the chart.

Pie usage

The <deckgo-pie-chart/> Web Component draw a Pie chart.

CSV

The csv file should contains at least two columns. The first one should be a label, which could be displayed or not, and the second one should be a value.

If more than two columns are provided, all columns beside the first one will be interpreted as values for comparison, in case you would like to displayed multiple graphs.

The values could be provided as number or percent.

Example

In this example, the first column contains a label for the category and the second contains the value in percent.

Wind;53.13% Solar:1.96% Geothermal;7.52% Landfill Gas;15.67% Biomass;14.79% Qualified Hydropower;6.93%

Properties

The <deckgo-pie-chart/> expose the following properties:

PropertyAttributeMandatoryDescriptionTypeDefault
srcsrcXThe path to the source file of the datastring
widthwidthXThe width of the chartnumber
heightheightXThe height of the chartnumber
innerRadiusinner-radiusTo plot a donut instead of a pie, provide an inner radiusnumber0
separatorseparatorThe line separator use in your csv filestring';'
animationanimationDisplay multiple graphs and animate the transition between thesebooleanfalse
animationDurationanimation-durationDuration of the transition between graphsnumer1000 (aka 1 second)
marginBottommargin-bottomThe margin bottom of the chart in pixelnumber64
marginLeftmargin-leftThe margin left of the chart in pixelnumber32
marginRightmargin-rightThe margin right of the chart in pixelnumber32
marginTopmargin-topThe margin top of the chart in pixelnumber8
customLoadercustom-loaderSet to true in case you would like to load (fetch) the data by yourself. Useful in case your data are protected with a token.booleanfalse

Note: if you would use customLoader the component will emit an event customLoad which the source of the data to load. You should subscribe to this event in order to process your custom load.

Styling

The <deckgo-pie-chart/> could be styled using the following CSS4 variables:

CSS4 variableDefaultNote
--deckgo-chart-text-colorblackThe color of the labels
--deckgo-chart-text-displayThe display property of the labels
--deckgo-chart-path-strokeThe stroke property of the pie, in case you would like to display a line between the slices
--deckgo-chart-text-font-sizeThe font size of the labels of the chart
--deckgo-chart-text-font-familyinheritThe font family of the labels of the chart
--deckgo-chart-positionrelativeThe position of the chart host
--deckgo-chart-displayblockThe display property of the chart host
--deckgo-chart-margin0The margin of the chart host
--deckgo-chart-svg-overflowThe overflow property of the svg generated by the chart
--deckgo-chart-svg-positionabsoluteThe position of the svg generated by the chart
--deckgo-chart-svg-top50%The top position of the svg generated by the chart
--deckgo-chart-svg-left50%The left position of the svg generated by the chart
--deckgo-chart-svg-translatetranslate(-50%, -50%)The translate property of the svg generated by the chart

Furthermore, as the Pie chart contains probably more than one slice, it will generate dynamically the following CSS4 variable for each slice of the pie where X is an index between 1 and the number of slices.

CSS4 variableDefaultNote
--deckgo-chart-fill-color-indexThe fill color of the slice identified with index X
--deckgo-chart-fill-opacity-indexThe opacity of the slice identified with index X
--deckgo-chart-stroke-indexThe stroke of the slice identified with index X
--deckgo-chart-stroke-width-indexThe stroke width of the slice identified with index X

Methods

The <deckgo-pie-chart/> expose the following methods.

Draw

In case you would like to redraw your chart, for example on resize of the window:

draw(width?: number, height?: number) => Promise<void>
Next

If you are using animation, this method is used to display the next data respectively the next chart.

async next()
Previous

If you are using animation, this method is used to display the previous data respectively the previous chart.

async prev()
Post load data

If you "manually" load the data, call this method once the text content fetched.

postCustomLoad(content: string | undefined);

Examples

You could find other examples of pie charts in the src/index.html of the project.

<deckgo-pie-chart width={500} height={400} src="https://raw.githubusercontent.com/deckgo/deckdeckgo/master/webcomponents/charts/showcase/data-pie-chart.csv"></deckgo-pie-chart>

Line usage

The <deckgo-line-chart/> Web Component draw a line chart.

CSV

The csv file should contains two or multiple columns.

The first column contains the values for the x axis. These should be provided as date or number.

The second and other columns contains the values for the y axis. These should be provided as number.

Use multiple columns in case you would like to compare multiple graphs.

Two columns

With dates as x axis:

01.01.2018;5 01.03.2018;10 01.06.2018;8

With numbers as x axis:

1;5 2;10 3;8
Three columns or more

The third columns or any others is optional, it could be use in case you would like to plot multiple charts on the same graph or animate a transition between these.

With dates as x axis:

01.01.2018;5;4 01.03.2018;10;3 01.06.2018;8;19

With numbers as x axis:

1;5;7 2;10;13 3;8;5

Properties

The <deckgo-line-chart/> expose the following properties:

PropertyAttributeMandatoryDescriptionTypeDefault
srcsrcXThe path to the source file of the datastring
widthwidthXThe width of the chartnumber
heightheightXThe height of the chartnumber
marginBottommargin-bottomThe margin bottom of the chart in pixelnumber32
marginLeftmargin-leftThe margin left of the chart in pixelnumber32
marginRightmargin-rightThe margin right of the chart in pixelnumber32
marginTopmargin-topThe margin top of the chart in pixelnumber32
datePatterndate-patternIn case the x are made of dates, the pattern to be use to parse the dates. Have a look to date-fns for a list of the supported format.string'yyyy-MM-dd'
yAxisDomainy-axis-domainShould the y axis plot the values from 0 to max or be extended (use extent) to cover all valuesstringmax
smoothsmoothDraw a smooth line or a line with edgesbooleantrue
areaareaDraw the area or just a linebooleantrue
ticksticksSpecify the ticks of the axisnumber``
gridgridDraw a grid behin the graphbooleanfalse
separatorseparatorThe line separator use in your csv filestring';'
animationanimationDisplay multiple graphs and animate the transition between thesebooleanfalse
animationDurationanimation-durationDuration of the transition between graphsnumer1000 (aka 1 second)
customLoadercustom-loaderSet to true in case you would like to load (fetch) the data by yourself. Useful in case your data are protected with a token.booleanfalse

Note: if you would use customLoader the component will emit an event customLoad which the source of the data to load. You should subscribe to this event in order to process your custom load.

Styling

The <deckgo-line-chart/> could be styled using the following CSS4 variables:

CSS4 variableDefaultNote
--deckgo-chart-axis-colorblackThe color of the axis
--deckgo-chart-text-colorblackThe color of the labels
--deckgo-chart-text-displayThe display property of the labels
--deckgo-chart-grid-stroke#989aa2The stroke of the grid
--deckgo-chart-grid-stroke-opacity0.7The stroke opacity of the grid
--deckgo-chart-strokeA default stroke which could be applied to all graphs' line
--deckgo-chart-text-font-sizeThe font size of the labels of the chart
--deckgo-chart-text-font-familyinheritThe font family of the labels of the chart
--deckgo-chart-positionrelativeThe position of the chart host
--deckgo-chart-displayblockThe display property of the chart host
--deckgo-chart-margin32pxThe margin of the chart host
--deckgo-chart-svg-overflowThe overflow property of the svg generated by the chart
--deckgo-chart-svg-positionabsoluteThe position of the svg generated by the chart
--deckgo-chart-svg-top50%The top position of the svg generated by the chart
--deckgo-chart-svg-left50%The left position of the svg generated by the chart
--deckgo-chart-svg-translatetranslate(-50%, -50%)The translate property of the svg generated by the chart

Furthermore, for each generated charts, the following CSS4 variables could be applied:

CSS4 variableDefaultNote
--deckgo-chart-fill-color-index#3880ffThe fill color of the area of the chart
--deckgo-chart-fill-opacity-indexThe opacity of the area of the chart
--deckgo-chart-stroke-indexThe stroke of the area of the chart
--deckgo-chart-stroke-width-indexThe stroke width of the area of the chart

Note: Replace -index with the index of the chart, for example: --deckgo-chart-fill-color-1: red;

Methods

The <deckgo-line-chart/> expose the following methods.

Draw

In case you would like to redraw your chart, for example on resize of the window:

draw(width?: number, height?: number) => Promise<void>
Next

If you are using animation, this method is used to display the next data respectively the next chart.

async next()
Previous

If you are using animation, this method is used to display the previous data respectively the previous chart.

async prev()
Post load data

If you "manually" load the data, call this method once the text content fetched.

postCustomLoad(content: string | undefined);

Examples

You could find other examples of line charts in the src/index.html of the project.

<deckgo-line-chart width={500} height={400} date-pattern="dd.MM.yyyy" src="https://raw.githubusercontent.com/deckgo/deckdeckgo/master/webcomponents/charts/showcase/data-line-chart.csv"></deckgo-line-chart>

Bar usage

The <deckgo-bar-chart/> Web Component draw a Bar chart.

CSV

The csv file should contains at least two columns. The first column should contains the labels. The other columns should contains values.

Use multiple columns in case you would like to compare multiple graphs.

The values could be provided as number or percent.

Multiple columns

The first column should contains the labels or groups used for the X axis. The other columns are the values use for the Y axis.

Group A;5;0;10 Group B;10;6;12 Group C;8;14;8 Group D;14;8;16 Group E;18;4;5

If you want to provide title for the bars, add a first row in your data with an empty value for the first column.

;Salami;Pastrami;Prosciutto Group A;5;0;10 Group B;10;6;12 Group C;8;14;8 Group D;14;8;16 Group E;18;4;5

Properties

The <deckgo-bar-chart/> expose the following properties:

PropertyAttributeMandatoryDescriptionTypeDefault
srcsrcXThe path to the source file of the datastring
widthwidthXThe width of the chartnumber
heightheightXThe height of the chartnumber
marginBottommargin-bottomThe margin bottom of the chart in pixelnumber32
marginLeftmargin-leftThe margin left of the chart in pixelnumber32
marginRightmargin-rightThe margin right of the chart in pixelnumber32
marginTopmargin-topThe margin top of the chart in pixelnumber32
separatorseparatorThe line separator use in your csv filestring';'
animationanimationDisplay multiple graphs and animate the transition between thesebooleanfalse
animationDurationanimation-durationDuration of the transition between graphsnumer1000 (aka 1 second)
datadataInstead of a source file it is also possible to provide the data of the chart as an objectDeckdeckgoBarChartData
yAxisy-axisIf false, no axis y will be draw.boolean
customLoadercustom-loaderSet to true in case you would like to load (fetch) the data by yourself. Useful in case your data are protected with a token.booleanfalse
yAxisMiny-axis-minSet a minimal value for the y Axis. Useful in case the series of data could contains only zeros.

Note: if you would use customLoader the component will emit an event customLoad which the source of the data to load. You should subscribe to this event in order to process your custom load.

Styling

The <deckgo-bar-chart/> could be styled using the following CSS4 variables:

CSS4 variableDefaultNote
--deckgo-chart-axis-colorblackThe color of the axis

Furthermore, as the Bar chart could draw dynamically multiple bars, it will generate dynamically the following CSS4 variable for each series of data where X is an index between 1 and the number of bars.

CSS4 variableDefaultNote
--deckgo-chart-text-colorThe color of the labels
--deckgo-chart-text-displayThe display property of the labels
--deckgo-chart-fill-color-indexThe fill color of the bar chart identified with index X
--deckgo-chart-fill-opacity-indexThe opacity of the bar chart identified with index X
--deckgo-chart-stroke-indexThe stroke of the bar chart identified with index X
--deckgo-chart-stroke-width-indexThe stroke width of the chart identified with index X
--deckgo-chart-text-font-sizeThe font size of the labels of the chart
--deckgo-chart-text-font-familyinheritThe font family of the labels of the chart
--deckgo-chart-positionrelativeThe position of the chart host
--deckgo-chart-displayblockThe display property of the chart host
--deckgo-chart-margin0The margin of the chart host
--deckgo-chart-svg-overflowThe overflow property of the svg generated by the chart
--deckgo-chart-svg-positionabsoluteThe position of the svg generated by the chart
--deckgo-chart-svg-top50%The top position of the svg generated by the chart
--deckgo-chart-svg-left50%The left position of the svg generated by the chart
--deckgo-chart-svg-translatetranslate(-50%, -50%)The translate property of the svg generated by the chart

Methods

The <deckgo-bar-chart/> expose the following methods:

Draw

In case you would like to redraw your chart, for example on resize of the window:

draw(width?: number, height?: number) => Promise<void>
Next

If you are using animation, this method is used to display the next data respectively the next chart.

async next()
Previous

If you are using animation, this method is used to display the previous data respectively the previous chart.

async prev()
Post load data

If you "manually" load the data, call this method once the text content fetched.

postCustomLoad(content: string | undefined);
Updating current bar

This is the method we are using to refresh the current bar chart when an audience is participating to live vote. It will not redraw the axis but it will draw and animate the bars.

async updateCurrentBar(values: DeckdeckgoBarChartDataValue[])

Examples

You could find other examples of bar charts in the src/index.html of the project.

<deckgo-bar-chart width={500} height={400} src="https://raw.githubusercontent.com/deckgo/deckdeckgo/master/webcomponents/charts/showcase/data-pie-chart.csv" style="--deckgo-chart-fill-color-1: #3880ff;"> </deckgo-bar-chart>