HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
Donut ChartView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA chart that shows parts of a whole as a ring, read from a table.StableSince 0.1.0ChartsUsageimport'@fusion.dev/helix/donut-chart'import'@fusion.dev/helix-headless/donut-chart'Preview
API ReferenceRoothelix-donut-chartA chart that shows parts of a whole as a ring, read from a table.
PropTypeDescriptiondataChartDataThe readings as data, in the shape of a table, where the page has no
table to point for at. for wins where both are set.emphasis"outlined"|"solid"|"subtle"How strongly the slices are drawn.emptyTextstringDefault"No readings"The words shown in place of the drawing when the table has no readings,
and the fallback of the empty slot.forstringDefault""The id of the table to read.hole"large"|"none"|"small"The size of the hole in the middle of the ring.labelstringDefault""The chart's name, which starts the chart's text summary.loadingbooleanDefaultfalseWhether the readings are still on their way. The chart shows
loading-text in place of an empty drawing until it has readings.loadingTextstringDefault"Loading readings"The words shown in place of the drawing while loading is set and
there are no readings yet, and the fallback of the loading slot.localestringDefault""The locale the chart's own numbers are written in: its axis, its
percentages and its totals, such as de for 1.240 and 32 %.material"frosted"|"glass"What the ring is made of.nextReadingsLabelstringDefault"Next readings"The name of the button that shows the next page of readings in the
table drawn from data, which holds a page at a time past
READINGS_PAGE.positionLabelstringDefault"{position} of {count}"Where a reading the keys moved to stands among the readings, said after
it. {position} and {count} are replaced with the numbers, written in
locale.previousReadingsLabelstringDefault"Previous readings"The name of the button that shows the previous page of readings in the
table drawn from data.readingsLabelstringDefault"Readings {first} to {last} of {count}"Which readings the page of the table drawn from data holds, said
beside its buttons and as each page arrives. {first}, {last} and
{count} are replaced with the numbers, written in locale.sliceLabelsbooleanDefaultfalseWrites each slice's share on the slice, the slice-label part, so a
reader sees the parts without a legend or a pointer: "29%" in the middle
of the band.sweep"half"How much of the circle the whole occupies.
ReadTypeDescriptionnamedstringThe chart's name: an aria-label written on the chart, then label,
then the table's caption.plottedColumnsnumber[]The positions of the cells in a row that hold numbers, in table order.readingsnumberThe number of readings, which the pointer position maps onto.seriesSeries[]The table's columns, one series each. Empty when there is no table.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)Content in the middle of the ring, usually a total. It is read by screen readers, while the ring itself is hidden from them.emptyContent shown in place of the ring when the table has no readings. Falls back to empty-text.loadingContent shown in place of the ring while loading is set and there are no readings yet. Falls back to loading-text.
EventTypeDescriptionhelix-reading-changeHelixReadingChangeEventThe slice shown moved, or was put away: index is the slice's row, or -1 for none, with its label and the pointerType that moved it.helix-reading-pressHelixReadingPressEventA slice was clicked, tapped, or pressed with Enter or Space, with the same detail as helix-reading-change.
MethodTypeDescriptioncolumnName(cell: number) => stringThe heading of the column at this place in a row: a cell's name is its
column's heading, read from the first row that has a cell there, so a
short first row does not lose the heading. '' where no row has one.seriesOf(cell: number) => number | undefinedThe palette slot for the cell at this position in a row.showsColumn(cell: number) => booleanWhether the series read from the cell at this place in a row is drawn,
by its column's heading. The keys and the readout pass over one a
legend hid.showsReading(at: number) => booleanWhether the slice at this place is drawn, which a slice a legend hid is
not. The keys pass over it, as the ring closes over it.showsSeries(name: string) => booleanWhether the series of this name is drawn, which it is unless a legend
reading the same table hid it.
PartDescriptioncenterThe middle of the ring, holding whatever is slotted.emptyThe words in place of the ring when the table has no readings: the empty slot, falling back to empty-text. Not drawn while the table cannot be read yet, on the server and during hydration.liveThe readout: a polite live region that says the slice the keys moved to. Hide it visually.loadingThe words in place of the ring while loading is set and there are no readings: the loading slot, falling back to loading-text.markThe invisible point the tooltip is anchored to.plotThe drawing, which takes focus to be read by key. With nothing to draw, a group named as the chart is, holding the empty or loading part.segmentOne slice.segment-activeThe slice under the pointer. Set alongside segment.segment-edgeOne slice as a closed shape, used to draw its outline.slice-labelOne slice's share, written on the slice under slice-labels. Placed with left and top, or inset-inline-start and top on a half ring, and carries its series color as --chart-series.summaryThe chart's name and each slice's share, written as a sentence for screen readers. Hide it visually.tableThe readings as a table, for a screen reader, rendered only where they were drawn from data, a page of them at a time past a few hundred. Hide it visually.table-pagesWhich readings a page of the table holds, and the buttons that show the previous and the next page, rendered only while it holds a page. Hide it visually.tooltip-anchorThe Tooltip element itself.tooltip-arrowThe bubble's point, forwarded from Tooltip.tooltip-arrow-bottomThe point while the bubble is below the reading, on its top edge. Set alongside tooltip-arrow.tooltip-arrow-leftThe point while the bubble is left of the reading, on its right edge. Set alongside tooltip-arrow.tooltip-arrow-rightThe point while the bubble is right of the reading, on its left edge. Set alongside tooltip-arrow.tooltip-arrow-topThe point while the bubble is above the reading, on its bottom edge. Set alongside tooltip-arrow.tooltip-cellOne column's name and value inside the tooltip.tooltip-cell-currentThe cell the series keys rest on, in the charts whose readings hold several series. A ring draws one, so it is never set here.tooltip-labelThe slice's own name inside the tooltip.tooltip-nameA column's name inside the tooltip.tooltip-surfaceThe bubble, forwarded from Tooltip.tooltip-surface-bottomThe bubble while it is below the reading. Set alongside tooltip-surface.tooltip-surface-leftThe bubble while it is left of the reading. Set alongside tooltip-surface.tooltip-surface-rightThe bubble while it is right of the reading. Set alongside tooltip-surface.tooltip-surface-topThe bubble while it is above the reading. Set alongside tooltip-surface.tooltip-valueA column's value inside the tooltip.trackThe ring the slices are drawn on.
CSS PropertyDescription--donut-chart-edge-strokeThickness of the slice boundary under outlined.--donut-chart-sizeWidth and height of the ring.--donut-chart-slice-label-background-colorPlate behind a slice's share, under slice-labels.--donut-chart-slice-label-colorColor of a slice's share, under slice-labels.--donut-chart-slice-label-font-sizeSize of a slice's share, under slice-labels.--donut-chart-strokeHow thick the ring is drawn, derived from hole.--donut-chart-track-colorColor of the ring under the slices.
Custom stateDescriptionactiveWhile a slice is shown, under the pointer or the keys, with its tooltip open.emptyWhile the empty part stands in place of the ring.loadingWhile the loading part stands in place of the ring.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-donut-chartA chart that shows parts of a whole as a ring, read from a table.
PropTypeDescriptiondataChartDataThe readings as data, in the shape of a table, where the page has no
table to point for at. for wins where both are set.emptyTextstringDefault"No readings"The words shown in place of the drawing when the table has no readings,
and the fallback of the empty slot.forstringDefault""The id of the table to read.hole"large"|"none"|"small"The size of the hole in the middle of the ring.labelstringDefault""The chart's name, which starts the chart's text summary.loadingbooleanDefaultfalseWhether the readings are still on their way. The chart shows
loading-text in place of an empty drawing until it has readings.loadingTextstringDefault"Loading readings"The words shown in place of the drawing while loading is set and
there are no readings yet, and the fallback of the loading slot.localestringDefault""The locale the chart's own numbers are written in: its axis, its
percentages and its totals, such as de for 1.240 and 32 %.nextReadingsLabelstringDefault"Next readings"The name of the button that shows the next page of readings in the
table drawn from data, which holds a page at a time past
READINGS_PAGE.positionLabelstringDefault"{position} of {count}"Where a reading the keys moved to stands among the readings, said after
it. {position} and {count} are replaced with the numbers, written in
locale.previousReadingsLabelstringDefault"Previous readings"The name of the button that shows the previous page of readings in the
table drawn from data.readingsLabelstringDefault"Readings {first} to {last} of {count}"Which readings the page of the table drawn from data holds, said
beside its buttons and as each page arrives. {first}, {last} and
{count} are replaced with the numbers, written in locale.sliceLabelsbooleanDefaultfalseWrites each slice's share on the slice, the slice-label part, so a
reader sees the parts without a legend or a pointer: "29%" in the middle
of the band.sweep"half"How much of the circle the whole occupies.
ReadTypeDescriptionnamedstringThe chart's name: an aria-label written on the chart, then label,
then the table's caption.plottedColumnsnumber[]The positions of the cells in a row that hold numbers, in table order.readingsnumberThe number of slices, which the keys walk.seriesSeries[]The table's columns, one series each. Empty when there is no table.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)Content in the middle of the ring, usually a total. It is read by screen readers, while the ring itself is hidden from them.emptyContent shown in place of the ring when the table has no readings. Falls back to empty-text.loadingContent shown in place of the ring while loading is set and there are no readings yet. Falls back to loading-text.
EventTypeDescriptionhelix-reading-changeHelixReadingChangeEventThe slice shown moved, or was put away: index is the slice's row, or -1 for none, with its label and the pointerType that moved it.helix-reading-pressHelixReadingPressEventA slice was clicked, tapped, or pressed with Enter or Space, with the same detail as helix-reading-change.
MethodTypeDescriptioncolumnName(cell: number) => stringThe heading of the column at this place in a row: a cell's name is its
column's heading, read from the first row that has a cell there, so a
short first row does not lose the heading. '' where no row has one.seriesOf(cell: number) => number | undefinedThe palette slot for a cell, which a ring gives its first plotted column
alone: it draws that column and no other, so a second numeric column is
no series the keys could move to.showsColumn(cell: number) => booleanWhether the series read from the cell at this place in a row is drawn,
by its column's heading. The keys and the readout pass over one a
legend hid.showsReading(at: number) => booleanWhether the slice at this place is drawn, which a slice a legend hid is
not. The keys pass over it, as the ring closes over it.showsSeries(name: string) => booleanWhether the series of this name is drawn, which it is unless a legend
reading the same table hid it.
PartDescriptioncenterThe middle of the ring, holding whatever is slotted.emptyThe words in place of the ring when the table has no readings: the empty slot, falling back to empty-text. Not drawn while the table cannot be read yet, on the server and during hydration.liveThe readout: a polite live region that says the slice the keys moved to. Hide it visually.loadingThe words in place of the ring while loading is set and there are no readings: the loading slot, falling back to loading-text.markThe invisible point the tooltip is anchored to.plotThe drawing, which takes focus to be read by key. With nothing to draw, a group named as the chart is, holding the empty or loading part.segmentOne slice.segment-activeThe slice under the pointer. Set alongside segment.segment-edgeOne slice as a closed shape, used to draw its outline.slice-labelOne slice's share, written on the slice under slice-labels. Placed with left and top, or inset-inline-start and top on a half ring, and carries its series color as --chart-series.summaryThe chart's name and each slice's share, written as a sentence for screen readers. Hide it visually.tableThe readings as a table, for a screen reader, rendered only where they were drawn from data, a page of them at a time past a few hundred. Hide it visually.table-pagesWhich readings a page of the table holds, and the buttons that show the previous and the next page, rendered only while it holds a page. Hide it visually.tooltip-anchorThe Tooltip element itself.tooltip-arrowThe bubble's point, forwarded from Tooltip.tooltip-arrow-bottomThe point while the bubble is below the reading, on its top edge. Set alongside tooltip-arrow.tooltip-arrow-leftThe point while the bubble is left of the reading, on its right edge. Set alongside tooltip-arrow.tooltip-arrow-rightThe point while the bubble is right of the reading, on its left edge. Set alongside tooltip-arrow.tooltip-arrow-topThe point while the bubble is above the reading, on its bottom edge. Set alongside tooltip-arrow.tooltip-cellOne column's name and value inside the tooltip.tooltip-cell-currentThe cell the series keys rest on, in the charts whose readings hold several series. A ring draws one, so it is never set here.tooltip-labelThe slice's own name inside the tooltip.tooltip-nameA column's name inside the tooltip.tooltip-surfaceThe bubble, forwarded from Tooltip.tooltip-surface-bottomThe bubble while it is below the reading. Set alongside tooltip-surface.tooltip-surface-leftThe bubble while it is left of the reading. Set alongside tooltip-surface.tooltip-surface-rightThe bubble while it is right of the reading. Set alongside tooltip-surface.tooltip-surface-topThe bubble while it is above the reading. Set alongside tooltip-surface.tooltip-valueA column's value inside the tooltip.trackThe ring the slices are drawn on.
CSS PropertyDescription--donut-chart-strokeHow thick the ring is drawn, derived from hole.
Custom stateDescriptionactiveWhile a slice is shown, under the pointer or the keys, with its tooltip open.emptyWhile the empty part stands in place of the ring.loadingWhile the loading part stands in place of the ring.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionArcThe same shares over a half circle, with the total in the opening.EmphasisThe three emphasis values, from full strength to a light wash.Large HoleA ring with a large hole, for a card where the total matters more than the shares.MaterialThe same ring opaque and as glass, over a background that shows the difference.PieA pie chart: the same drawing with the hole closed, so the ring spans the whole radius.PreviewSessions by source as a ring, read from the table beside it.PreviewSessions by source as a ring, read from the table beside it.Slice LabelsEach share written on its slice with slice-labels.With A LegendA legend beside the ring, mapping the same palette in the same order.With A TotalA total in the middle of the ring.