Semantic Indicator
Vertical semantic color strip or progress rail—maps alert and priority states to tokens, optionally filled by value.
SemanticIndicator is a vertical bar built on Radix Progress. Omit value for a solid semantic strip; pass value (and optional max) for a determinate fill in the same state color. Use size for thickness.
Installation
The component is exported from @by/experience-system. Add the package with your package manager:
pnpm add @by/experience-systemIn this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.
Composition
Use the following composition to render a SemanticIndicator:
SemanticIndicator
└── (internal Progress.Indicator — only when `value` is set)The root is Radix Progress.Root with data-slot="semantic-indicator". When value is provided, an internal Progress.Indicator renders the fill (data-slot="semantic-indicator-fill"). Behavior follows Radix Progress.
Usage
import { SemanticIndicator } from '@by/experience-system';SemanticIndicator is a client component ('use client'). Use it inside a Client Component or a dynamic import when using the Next.js App Router. Place it in a container with a defined height (for example h-32 on a flex parent with items-stretch) so the vertical bar is visible.
<div className="flex h-32 items-stretch gap-2">
<SemanticIndicator state="success" />
<SemanticIndicator state="info" value={66} max={100} />
</div>When to use
Use for compact lane or rail indicators next to lists, cards, or steppers where color encodes status or priority. Use the value form when the same rail should double as a thin progress indicator.
When not to use
For a standard horizontal task bar or labeled completion percentage, prefer Progress or Circular progress with Field / FieldLabel.
Examples
Overview
Determinate vertical bar with default state, size="md", value={66}, and max={100}—same setup as the preview at the top of this page.
States
Solid strips without value for each supported state (default, alert row, then priority row).
Sizes
sm, md, and lg change track width; value is set so the fill height is comparable across sizes.
API Reference
SemanticIndicator wraps Radix UI Progress Progress.Root and, when value is set, Progress.Indicator. The prop tables for the root mirror the upstream Root API; value and max are extended for the solid-strip versus determinate modes described above. The internal indicator inherits the same [data-state], [data-value], and [data-max] attributes as in the Radix docs. The package also exports PRIORITY_STATES, ALERT_STATES, and types PriorityState, AlertState, SemanticIndicatorState.
SemanticIndicator
| Prop | Type | Default |
|---|---|---|
asChild | boolean | false |
value | number | — (omit for solid strip; when set, renders determinate fill) |
max | number | 100 |
getValueLabel | (value: number, max: number) => string | No default value |
state | default | success | warning | error | info | neutral | critical | high | medium | low | default |
size | sm | md | lg | md |
Also accepts additional props accepted by Radix Progress.Root (such as id, style, className, aria-*) except value and max, which use the signatures above.
| Data attribute | Values |
|---|---|
[data-state] | "complete" | "indeterminate" | "loading" |
[data-value] | The current value (present when determinate) |
[data-max] | The max value (present when determinate) |
data-slot | semantic-indicator on the root; semantic-indicator-fill on the indicator when value is set |
Accessibility
The root exposes role="progressbar". When value is set, aria-valuenow, aria-valuemin, and aria-valuemax follow Radix Progress. When value is omitted, the bar is indeterminate (no aria-valuenow); use this only when that matches the intended semantics, or mark purely decorative rails with aria-hidden and ensure meaning is available elsewhere. Provide getValueLabel when the default value text should be customized for assistive technology, and pair the control with a visible label (Field / FieldLabel, aria-labelledby, or aria-label) when it communicates status or quantity. See Radix Progress — Accessibility and the progressbar role.
Source in the repo: packages/experience-system/src/components/SemanticIndicator/SemanticIndicator.tsx and variants.ts. Agent-oriented contracts: packages/experience-system/src/components/SemanticIndicator/SemanticIndicator.instructions.md.