CompositionBar
A single horizontal stacked bar with a legend that shows how parts make up a total, such as a budget breakdown, a token allocation, or a storage split.
Playground
Share A 60 · 60.0%
Share B 30 · 30.0%
Share C 10 · 10.0%
| Share | Value | Percent |
|---|---|---|
| Share A | 60 | 60.0% |
| Share B | 30 | 30.0% |
| Share C | 10 | 10.0% |
Orientation V Style variant
Size V Style variant
·
<script lang="ts">
import { CompositionBar } from '@urbicon-ui/blocks';
const items = [
{ label: 'Share A', value: 60, intent: 'primary' },
{ label: 'Share B', value: 30, intent: 'success' },
{ label: 'Share C', value: 10, intent: 'warning' }
];
</script>
<CompositionBar
{items}
/>01 Examples
Heating Cost Pot
Stacked bar as a cost-pot composition: gas + heat pump electricity + maintenance + chimney sweep add up to the heating cost pot of a service charge statement.
Heating cost pot 2024 €3,822.42
Gas bill €2,206.09 · 57.7%
Heat pump electricity €1,127.31 · 29.5%
Heating system maintenance €361.02 · 9.4%
Chimney sweep levy €128.00 · 3.3%
| Share | Value | Percent |
|---|---|---|
| Gas bill | €2,206.09 | 57.7% |
| Heat pump electricity | €1,127.31 | 29.5% |
| Heating system maintenance | €361.02 | 9.4% |
| Chimney sweep levy | €128.00 | 3.3% |
·
<div class="w-full max-w-xl">
<CompositionBar
items={heatingItems}
formatValue={formatEur}
size="lg"
legendPlacement="bottom"
showTotal
totalLabel="Heating cost pot 2024"
/>
</div>Tiny Segments
Very small segments are raised to a minimum width so hover and tooltip still work on them.
Main share 950 · 98.3%
Mini A 8 · 0.8%
Mini B 3 · 0.3%
Mini C 5 · 0.5%
| Share | Value | Percent |
|---|---|---|
| Main share | 950 | 98.3% |
| Mini A | 8 | 0.8% |
| Mini B | 3 | 0.3% |
| Mini C | 5 | 0.5% |
·
<div class="w-full max-w-xl">
<CompositionBar items={tinyItems} formatValue={(v) => `${v}`} size="lg" />
</div>Total Override (Remainder)
If the explicit total exceeds the sum of the item values, the unaccounted share is rendered as a dashed remainder area.
Expected €5,000.00 €5,000.00
Gas bill €2,206.09 · 44.1%
Heat pump electricity €1,127.31 · 22.5%
Heating system maintenance €361.02 · 7.2%
Chimney sweep levy €128.00 · 2.6%
23.6%
| Share | Value | Percent |
|---|---|---|
| Gas bill | €2,206.09 | 44.1% |
| Heat pump electricity | €1,127.31 | 22.5% |
| Heating system maintenance | €361.02 | 7.2% |
| Chimney sweep levy | €128.00 | 2.6% |
| Expected €5,000.00 (remaining) | €1,177.58 | 23.6% |
·
<div class="w-full max-w-xl">
<CompositionBar
items={heatingItems}
total={500000}
formatValue={formatEur}
size="lg"
showTotal
totalLabel="Expected €5,000.00"
/>
</div>Raw Color Overrides
Give each item a color (any CSS colour) instead of a semantic intent, for a brand-specific palette like this token allocation.
Treasury 40% · 40%
Liquidity 30% · 30%
Team 15% · 15%
Community 15% · 15%
| Share | Value | Percent |
|---|---|---|
| Treasury | 40% | 40% |
| Liquidity | 30% | 30% |
| Team | 15% | 15% |
| Community | 15% | 15% |
·
<div class="w-full max-w-xl">
<CompositionBar
items={tokenItems}
formatValue={(v) => `${v}%`}
formatPercent={(p) => `${Math.round(p)}%`}
size="lg"
legendPlacement="bottom"
/>
</div>02 Customization
Custom Tooltip Snippet
Custom tooltip content with additional metadata via the tooltip snippet.
Gas bill €2,206.09 · 58%
Heat pump electricity €1,127.31 · 29%
Heating system maintenance €361.02 · 9%
Chimney sweep levy €128.00 · 3% statutory levy
| Share | Value | Percent |
|---|---|---|
| Gas bill | €2,206.09 | 57.7% |
| Heat pump electricity | €1,127.31 | 29.5% |
| Heating system maintenance | €361.02 | 9.4% |
| Chimney sweep levy | €128.00 | 3.3% |
·
<div class="w-full max-w-xl">
<CompositionBar items={heatingItems} formatValue={formatEur} size="lg">
{#snippet tooltip(item, percent)}
<span class="block font-medium">{item.label}</span>
<span class="text-text-tertiary text-2xs block tabular-nums">
{formatEur(item.value)} · {Math.round(percent)}%
</span>
{#if item.intent === 'warning'}
<span class="text-warning-text text-3xs mt-1 block tracking-wide uppercase">
statutory levy
</span>
{/if}
{/snippet}
</CompositionBar>
</div>Compact Card Embedding
Embedded in a card with a header at the sm size.
Treasury Allocation
Q1 2026 Treasury 40% · 40%
Liquidity 30% · 30%
Team 15% · 15%
Community 15% · 15%
| Share | Value | Percent |
|---|---|---|
| Treasury | 40% | 40% |
| Liquidity | 30% | 30% |
| Team | 15% | 15% |
| Community | 15% | 15% |
·
<div class="border-border-subtle bg-surface-elevated w-full max-w-md rounded-2xl border p-5">
<header class="mb-3 flex items-baseline justify-between">
<h3 class="text-text-primary text-sm font-semibold">Treasury Allocation</h3>
<span class="text-text-tertiary text-xs">Q1 2026</span>
</header>
<CompositionBar
items={tokenItems}
formatValue={(v) => `${v}%`}
formatPercent={(p) => `${Math.round(p)}%`}
size="sm"
legendPlacement="bottom"
/>
</div>03 Accessibility
Group Role + Summary
The bar container has role="group" with an aria-label summary: the total, the number of shares and
each share's percent.
Table Fallback
An sr-only table repeats the data as rows of share, value and percent.
Keyboard Navigation
Tab focuses the next segment, Arrow keys move between segments, Home /End jump to the first/last, Enter/Space triggers onItemSelect.
Bidirectional Highlight
Hovering or focusing a bar segment dims the other segments and highlights the matching legend entry, and the reverse holds too.
04 API Reference
25 props25 props · 1 required
Add filter
Sort
Grouping · No column can be grouped
Summary · No column can be summarized
Column visibility
Prop | Type | Default | Description | |
|---|---|---|---|---|
items required | CompositionItem[] | — | Composition shares in the order they should appear in the bar. | |
class | string | — | Extra classes merged onto the wrapper. | |
dimmed variant | truefalse | — | Controls the dimmed behavior and appearance of the CompositionBar component. Available options: true, false. | |
fill variant | primarysecondarysuccesswarning +2 more | — | Controls the fill behavior and appearance of the CompositionBar component. Available options: primary, secondary, success, and 3 more. | |
formatPercent | (percent: number) => string | — | Format function for percentages, which arrive on a 0–100 scale. Default: 1 fraction
digit, with the sign placed by the active locale (12.3% in English, 12,3 % with a
no-break space in German). | |
formatValue | (value: number) => string | — | Format function for values (tooltip, legend, total). | |
intent | CompositionBarIntent primarysecondarysuccesswarning +2 more | 'primary' | Default intent for items without their own intent/color. | |
legendItem | Snippet<[item: CompositionItem, percent: number]> | — | Custom rendering of a legend entry. Receives the item and its percentage.
Fully replaces the default rendering (dot + label + value/percent). The entry's
accessible name stays label: value, percent, so the text the snippet shows has to
be contained in it (WCAG 2.5.3). | |
legendPlacement variant | toprightbottomleft | bottom | Controls the legendPlacement behavior and appearance of the CompositionBar component. Available options: top, right, bottom, left. | |
minSegmentPercent | number | 1.5 | Minimum segment width in percent. Values below it are raised to this
width so small shares stay visible. The other segments and the remainder
of a larger total give up that space in proportion to their shares, and
none ends up narrower than a raised segment unless it started below the minimum.
If the minimums alone would fill the bar, no segment is raised. Names, the
summary and the screen-reader table keep each item's own percent. | |
onItemSelect | (item: CompositionItem, index: number) => void | — | Selection callback fired when a bar segment or legend entry is clicked. Receives the item and its index. Providing it makes the segments interactive (pointer cursor and click handling). | |
orientation variant | horizontalvertical | horizontal | Controls the orientation behavior and appearance of the CompositionBar component. Available options: horizontal, vertical. | |
preset | string | — | Preset name (registered via <BlocksProvider presets={{ CompositionBar: {...} }}>). | |
showLegend | boolean | true | Show the legend. Position it with legendPlacement. | |
showPercentages | boolean | true | Show percentages in legend and tooltip. | |
showTotal | boolean | false | Render the total value after the legend. | |
showValues | boolean | false | Render the value directly inside the bar segment, in addition to the legend. Only segments wide enough (≥ 8% or ~40 px) show their value, so narrow ones do not overflow. Handy for print or PDF export, where there is no hover tooltip. | |
size variant | smmdlg | md | Controls the dimensions, padding, and text size of the CompositionBar. Affects the component's physical footprint. Available options: sm, md, lg. | |
slotClasses | Partial<Record<CompositionBarSlots, string>> | — | Per-slot class overrides. | |
tooltip | Snippet<[item: CompositionItem, percent: number]> | — | Custom tooltip content. Replaces the default layout (label, value, percent). | |
total | number | — | Optional fixed total value. Default: the sum of the item values. If the explicit total exceeds the sum, the remaining area is rendered neutrally ("unaccounted share"). If it is below the sum, segments are scaled to 100% and a console warning is emitted. | |
totalLabel | string | — | Label rendered before the total. Defaults to the localized "Total" label from the blocks i18n bundle. | |
unstyled | boolean | — | Remove all default classes; only the layout structure remains. | |
...CompositionBarVariants variant | VariantProps | — | Styling variants from CompositionBarVariants | |
...HTMLAttributes<HTMLDivElement> inherited | HTMLAttributes | — | HTML attributes (excluding: 'children') |
05 Types
4 types
Name | Kind | Category | Used by | Description | |
|---|---|---|---|---|---|
CompositionBarIntent | type | helper | 1 | — | |
CompositionItem | interface | helper | 1 | A single share in the stacked bar. | |
CompositionBarProps | interface | props | — | — | |
CompositionBarVariants | type | variant | — | — |
06 Installation
Import
·
import { CompositionBar } from '@urbicon-ui/blocks';