Share Bar

import { Card, CardContent } from "@/components/ui/card"
import { ShareBar, type ShareBarItem } from "@/components/ui/share-bar"

Use a share bar to show how a total splits into parts, such as spending by category or who paid what on a shared bill. It draws one color at falling density, never several hues, and keeps at most four segments so the bar stays readable. Pick a chart when the parts change over time, and a key-value list when the exact amounts matter more than the proportions.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/share-bar
Copy

Usage#

Copyimport { ShareBar } from "@/components/ui/share-bar"

Copy<ShareBar
  currency="USD"
  items={[
    { label: "Shopping", value: 772.9 },
    { label: "Food", value: 515.3 },
    { label: "Transport", value: 331.2 },
  ]}
/>

Composition#

ShareBar renders the bar and its legend on its own. Pass children to choose the parts yourself:

CopyShareBar
├── ShareBarTrack
└── ShareBarLegend
    └── ShareBarSwatch

Features#

• One color at falling density, in the order you pass the items
• At most four segments; the tail is merged into one "Other" segment
• Whole percents that always add up to 100, with <1% for a small non-zero share
• Legend values as money when currency is set, or as plain numbers
• The bar is read by screen readers as one image that lists every share
• A custom legend row through a render function

Merged tail#

Pass the items largest first. When there are more items than maxSegments, the rest are added up into one segment named by otherLabel. The demo at the top passes five categories, so the last two become "Other".

Copy<ShareBar items={spending} maxSegments={3} otherLabel="Everything else" />

Custom legend#

Pass a function as the child of ShareBarLegend to render each row yourself. Use ShareBarSwatch with the segment's tone to keep the color key.

"use client"

import { MoneyAmount } from "@/components/ui/money-amount"

Counts#

Leave out currency to show plain numbers, such as payments by method.

import { ShareBar, type ShareBarItem } from "@/components/ui/share-bar"

const payments: ShareBarItem[] = [

Bar only#

Render only ShareBarTrack for a compact summary under a heading. Its aria-label is put before the generated list of shares.

import {
  ShareBar,
  ShareBarTrack,

Empty#

When every value is 0, the track renders empty, the legend shows 0% for each item and screen readers hear "No data".

import { ShareBar } from "@/components/ui/share-bar"

export function ShareBarEmpty() {

Accessibility#

ShareBarTrack has role="img" and a name built from the segments, for example "Shopping 42%, Food 28%". The segments themselves are hidden from screen readers. ShareBarLegend is a real list, and ShareBarSwatch is decorative.

Name the bar#

Give the track an aria-label that says what is split. It is put before the shares.

Copy<ShareBarTrack aria-label="Spent in November" />

This is read as "Spent in November: Shopping 44%, Food 29%, …".

Meaning beyond color#

Segments differ only by density. Keep the legend, or a nearby label with the amounts, so the split is not conveyed by color alone.

API Reference#

ShareBar#

The root. Works out the segments and shares them with its parts. Renders a div and accepts all of its props.

ShareBarTrack#

The bar. Renders a div with role="img" and accepts all of its props except children.

ShareBarLegend#

The parts in bar order: swatch, label, value and share. Renders a ul and accepts all of its props.

ShareBarSwatch#

The color key of one segment, for custom legend rows. Renders a decorative span.

ShareBarItem#

One part you pass in items.

ShareBarSegment#

What a custom legend row receives.

useShareBar#

Reads segments, total, currency and locale inside a ShareBar. Throws outside of one.

formatSharePercent#

Formats a segment's share as text: "42%", or "<1%" for a small non-zero share.

CopyformatSharePercent(segment) // "42%"