Skip to main content

Donut

Reusable Donut Chart API class that renders a simple and configurable donut chart.

Example

import { donut } from '@britecharts/core';

// dataset: [{ name, quantity, id }]
const donutChart = donut();

donutChart
    .externalRadius(500)
    .internalRadius(200)
    .render('.css-selector', dataset);

donut(_selection, _data)​

This function creates the graph using the selection as container

Kind: Exported function

ParamTypeDescription
_selectionD3SelectionA d3 selection that represents the container(s) where the chart(s) will be rendered
_dataDonutChartDataThe data to attach and generate the chart

a11yTitle(_x) ⇒ String | null | module​

Gets or Sets the name screen readers announce for the chart. It is set as the svg's aria-label. Unset, the chart is announced as "Donut chart".

Kind: method of donut
Returns: String | null | module - Current a11yTitle or Chart module to chain calls
Access: public

ParamTypeDescription
_xString | nullDesired accessible title for the chart

a11yDescription(_x) ⇒ String | null | module​

Gets or Sets a longer description screen readers announce after the chart's name, such as what the data shows. It is rendered as the svg's <desc>. Unset, the chart has no description.

Kind: method of donut
Returns: String | null | module - Current a11yDescription or Chart module to chain calls
Access: public

ParamTypeDescription
_xString | nullDesired accessible description for the chart

a11yDataTable(_x) ⇒ Boolean | module​

Gets or Sets whether the chart renders its data as a visually hidden table after its svg, which screen readers can read cell by cell. On by default; set it to false when the app gives the data its own accessible form.

Kind: method of donut
Returns: Boolean | module - Current a11yDataTable or Chart module to chain calls
Access: public

ParamTypeDescription
_xBooleanWhether to render the data table

a11yKeyboardNavigation(_x) ⇒ Boolean | module​

Gets or Sets whether a keyboard can move through the chart's data points: the chart takes one tab stop, the arrow keys move between points, Home and End go to the first and last, and Escape lets go. The tooltip and highlights follow focus as they follow the pointer. On by default.

Kind: method of donut
Returns: Boolean | module - Current a11yKeyboardNavigation or Chart module to chain calls
Access: public

ParamTypeDescription
_xBooleanWhether the keyboard can move through the data

animationDuration(_x) ⇒ duration | module​

Gets or Sets the duration of the animation

Kind: method of donut
Returns: duration | module - Current animation duration or Chart module to chain calls
Access: public

ParamTypeDefaultDescription
_xNumber1200Desired animation duration for the graph

centeredTextFunction(_x) ⇒ function | module​

Gets or Sets the centeredTextFunction of the chart. If function is provided the format will be changed by the custom function's value format. The default format function value is "${d.percentage}% ${d.name}". The callback will provide the data object with id, name, percentage, and quantity. Also provides the component added by the user in each data entry.

Kind: method of donut
Returns: function | module - Current centeredTextFunction or Chart module to chain calls
Access: public

ParamTypeDescription
_xfunctionCustom function that returns a formatted string

Example

donutChart.centeredTextFunction(d => `${d.id} ${d.quantity}`)

colorMap([_x]) ⇒ number | module​

Gets or Sets the colorMap of the chart

Kind: method of donut
Returns: number | module - Current colorMap or Chart module to chain calls
Access: public

ParamTypeDefaultDescription
[_x]object
Color map

Example

stackedBar.colorMap({groupName: 'colorHex', groupName2: 'colorString'})

colorSchema(_x) ⇒ String | module​

Gets or Sets the colorSchema of the chart

Kind: method of donut
Returns: String | module - Current colorSchema or Chart module to chain calls
Access: public

ParamTypeDescription
_xArray.<String>Desired colorSchema for the graph

emptyDataConfig(_x) ⇒ Object | module​

Gets or Sets the emptyDataConfig of the chart. If set and data is empty (quantity adds up to zero or there are no entries), the chart will render an empty slice with a given color (light gray by default)

Kind: method of donut
Returns: Object | module - Current config for when chart data is an empty array
Access: public

ParamTypeDescription
_xObjectEmptyDataConfig object to get/set

Example

donutChart.emptyDataConfig({showEmptySlice: true, emptySliceColor: '#000000'})

exportChart(filename, title) ⇒ Promise​

Exports the chart and fires a download: an svg file when the filename ends in .svg, and a png otherwise

Kind: method of donut
Returns: Promise - Promise that resolves if the chart image was loaded and downloaded successfully
Access: public

ParamTypeDescription
filenameStringName of the downloaded file, whose extension picks the format
titleStringTitle to add at the top of the exported picture

externalRadius(_x) ⇒ Number | Module​

Gets or Sets the externalRadius of the chart

Kind: method of donut
Returns: Number | Module - Current externalRadius or Donut Chart module to chain calls
Access: public

ParamTypeDescription
_xNumberExternalRadius number to get/set

hasCenterLegend(_x) ⇒ boolean | Module​

Gets or Sets the hasCenterLegend property of the chart, making it display legend at the center of the donut.

Kind: method of donut
Returns: boolean | Module - Current hasCenterLegend flag or Chart module
Access: public

ParamTypeDescription
_xbooleanIf we want to show legent at the center of the donut

hasHoverAnimation(_x) ⇒ boolean | module​

Gets or Sets the hasHoverAnimation property of the chart. By default, donut chart highlights the hovered slice. This property explicitly disables this hover behavior.

Kind: method of donut
Returns: boolean | module - Current hasHoverAnimation flag or Chart module
Access: public

ParamTypeDescription
_xbooleanDecide whether hover slice animation should be enabled

hasFixedHighlightedSlice(_x) ⇒ boolean | module​

Gets or Sets the hasFixedHighlightedSlice property of the chart, making it to highlight the selected slice id set with highlightSliceById all the time.

Kind: method of donut
Returns: boolean | module - Current hasFixedHighlightedSlice flag or Chart module
Access: public

ParamTypeDescription
_xbooleanIf we want to make the highlighted slice permanently highlighted

hasLastHoverSliceHighlighted(_x) ⇒ boolean | module​

Gets or sets the hasLastHoverSliceHighlighted property. If property is true, the last hovered slice will be highlighted after 'mouseout` event is triggered. The last hovered slice will remain in highlight state. Note: if both hasFixedHighlightedSlice and hasLastHoverSliceHighlighted are true, the latter property will override the former.

Kind: method of donut
Returns: boolean | module - Current hasLastHoverSliceHighlighted value or Chart module
Access: public

ParamTypeDescription
_xbooleanDecide whether the last hovered slice should be highlighted

height(_x) ⇒ Number | Module​

Gets or Sets the height of the chart

Kind: method of donut
Returns: Number | Module - Current height or Donut Chart module to chain calls
Access: public

ParamTypeDescription
_xNumberDesired width for the graph

highlightSliceById(_x) ⇒ Number | Module​

Gets or Sets the id of the slice to highlight

Kind: method of donut
Returns: Number | Module - Current highlighted slice id or Donut Chart module to chain calls
Access: public

ParamTypeDescription
_xNumberSlice id

internalRadius(_x) ⇒ Number | Module​

Gets or Sets the internalRadius of the chart

Kind: method of donut
Returns: Number | Module - Current internalRadius or Donut Chart module to chain calls
Access: public

ParamTypeDescription
_xNumberInternalRadius number to get/set

isAnimated(_x) ⇒ Boolean | module​

Gets or Sets the isAnimated property of the chart, making it to animate when render. The chart draws without animation when the reader's system asks for reduced motion (prefers-reduced-motion), whatever this is set to. By default this is 'false'

Kind: method of donut
Returns: Boolean | module - Current isAnimated flag or Chart module
Access: public

ParamTypeDescription
_xBooleanDesired animation flag

isLoading(flag) ⇒ boolean | module​

Gets or Sets the loading state of the chart

Kind: method of donut
Returns: boolean | module - Current loading state flag or Chart module to chain calls
Access: public

ParamTypeDescription
flagbooleanDesired value for the loading state

margin(_x) ⇒ Object | Module​

Gets or Sets the margin of the chart

Kind: method of donut
Returns: Object | Module - Current margin or Donut Chart module to chain calls
Access: public

ParamTypeDescription
_xObjectMargin object to get/set

numberFormat(_x) ⇒ string | module​

Gets or Sets the number format of the donut chart

Kind: method of donut
Returns: string | module - Current numberFormat or Chart module to chain calls
Access: public

ParamTypeDescription
_xstringDesired numberFormat for the chart. See examples here

on() ⇒ module​

Exposes an 'on' method that acts as a bridge with the event dispatcher We are going to expose this events: customMouseOver, customMouseMove, customMouseOut and customClick

Kind: method of donut
Returns: module - Bar Chart
Access: public

orderingFunction(_x) ⇒ function | Module​

Changes the order of items given custom function

Kind: method of donut
Returns: function | Module - Void function with no return
Access: public

ParamTypeDescription
_xfunctionA custom function that sets logic for ordering

percentageFormat(_x) ⇒ Number | Module​

Gets or Sets the percentage format for the percentage label

Kind: method of donut
Returns: Number | Module - Current format or Donut Chart module to chain calls
Access: public

ParamTypeDescription
_xStringFormat for the percentage label (e.g. '.1f')

radiusHoverOffset(_x) ⇒ Number | Module​

Gets or Sets the radiusHoverOffset of the chart

Kind: method of donut
Returns: Number | Module - Current offset or Donut Chart module to chain calls
Access: public

ParamTypeDescription
_xNumberDesired offset for the hovered slice

width(_x) ⇒ Number | Module​

Gets or Sets the width of the chart

Kind: method of donut
Returns: Number | Module - Current width or Donut Chart module to chain calls
Access: public

ParamTypeDescription
_xNumberDesired width for the graph

render(target, [data]) ⇒ module​

Draws the chart into a target: a CSS selector, an element or a d3 selection, as select(target).datum(data).call(chart) does. A selector draws into the first element it matches. Without data, the chart redraws with the data it last drew there.

Kind: method of donut
Returns: module - The chart module, to chain calls
Throws:

  • Error When the target matches no element

Access: public

ParamTypeDescription
targetString | Element | D3SelectionWhere to draw the chart
[data]ObjectThe data to draw

Example

donut().width(600).render('#chart', data);

exports~DonutChartData : Array.<Object>​

Kind: inner typedef of donut
Properties

NameTypeDescription
quantityNumberQuantity of the group (required)
percentageNumberPercentage of the total (optional)
nameStringName of the group (required)
idNumberIdentifier for the group required for legend feature (optional)

Example

[
    {
        quantity: 1,
        percentage: 50,
        name: 'glittering',
        id: 1
    },
    {
        quantity: 1,
        percentage: 50,
        name: 'luminous',
        id: 2
    }
]