Skip to content

Block Bar

Unicode block-character bar for displaying proportional values. Supports single-value and multi-segment stacked bars.

Preview

Installation

$pnpm exec dgadd add ui/block-bar
[Installs to]src/components/ui/block-bar[Item]ui/block-bar

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.

Usage

tsx
import { BlockBar } from "@/components/ui/block-bar";export default function BlockBarDefault() {  return <BlockBar label="Progress" value={14} max={20} />;}

Examples

Stats

Preview

Multi-Segment

Preview

API Reference

BlockBar

NameTypeDefaultDescription
valuenumber0Current value. Defaults to zero when omitted without segments or BlockBar.Segment children; otherwise the value is derived from their sum.
maxrequirednumber—Maximum value the bar represents. Used for aria-valuemax and fill ratio.
barWidthnumber20Width of the bar in character cells. Clamped to 0-200.
filledCharstring"█"Character used for the filled portion of the bar.
emptyCharstring"░"Character used for the empty portion of the bar.
labelstring—Visible label rendered to the left of the bar in simple mode. Also used as accessible name when aria-label is omitted.
aria-labelstring—Accessible name. When set (or label is set), the bar exposes role="meter" with aria-valuemin/max/now/text.
aria-labelledbystring—ID of an element labelling the bar. Alternative to aria-label.
valueTextstring"{value} of {max}"Override for aria-valuetext.
variant"default" | "muted" | "error" | "warning" | "success" | "info""default"Color token applied to the implicit single segment when no segments or children are provided.
segments{ value: number; variant?: SegmentVariant; char?: string; className?: string }[]—Multi-segment stack. When provided, takes precedence over children and derives value from the sum. Cells are allocated collectively across segments in order.
childrenReactNode—BlockBar.Segment children for fully custom rendering. Cells are allocated collectively across segment children. Throws when neither value nor segments are provided and children are not BlockBar.Segment elements.

BlockBar.Segment

NameTypeDefaultDescription
valuerequirednumber—Segment value in the same units as BlockBar max.
variant"default" | "muted" | "error" | "warning" | "success" | "info""default"Segment color token.
charstringBlockBar filledCharOverride the filled character for this segment only.
childrenReactNode—Optional content rendered after the segment glyphs (e.g. a label or icon).

Accessibility

Notes

Simple Mode

Single-value bar: <BlockBar label="Errors" value={3} max={45} variant="error" />. Label, bar, and value display are rendered automatically.

Multi-Segment Mode

Pass a segments array: segments={[{ value: 60, variant: 'success' }, { value: 25, variant: 'warning' }]}. Value is derived from the segment sum unless explicitly provided. Cells are allocated across ordered segments, so an exact max-total fills the configured width without clipping later segments. When segments and children are both provided, segments win and define rendering and value. Each segment also accepts className for app-owned colors the built-in variants do not cover.

Compound Mode

Pass BlockBar.Segment children for custom per-segment content (labels, event handlers, tooltips). Cells are allocated across the segment children in order. Root renders the empty background automatically.

Value Text

Set valueText to customize aria-valuetext for app-owned labels such as severity summaries. The visible value remains numeric.

Color Variants

The variant prop accepts: default, muted, error, warning, success, info.

Custom Characters

filledChar (default: █) and emptyChar (default: ░) control the block characters. Individual segments can override with the char prop.

Source

Install via CLI: pnpm exec dgadd add ui/block-bar.

Highlighted source loads after this disclosure opens. Browse the source repository.