Status badge

Pass the status key from your data, and a statuses map if the defaults (operational, degraded, outage, maintenance, pending, active, complete, failed, cancelled, draft) do not fit. It renders one static span. It does not fetch or poll status, does not decide what a status means, and is not announced when it changes unless you wrap it in a live region.

Suggested location

src/lib/components/status-badge-01

Required props

status

Limitations

• Passing statuses replaces the default map instead of merging with it. Spread DEFAULT_STATUSES from statuses.ts into your map to keep the defaults.
• The label never wraps. Past the width of its container it truncates with an ellipsis, so keep labels to one to three words.
• Not a live region. If the status changes in place, wrap the badge in an element with role="status" so the change is announced.
• The development warning for an unknown key reads import.meta.env.DEV, which Vite sets; other bundlers stay silent.
• Light mode only. On a dark page set --status-badge-muted, --status-badge-hairline, --status-badge-surface and each tone to lighter colours, and re-check contrast.

Example

<script lang="ts">
	import StatusBadge from '$lib/components/status-badge-01/StatusBadge.svelte';
	import type { StatusMap } from '$lib/components/status-badge-01/statuses.js';

	const orderStatuses: StatusMap = {
		paid: { label: 'Paid', tone: 'success' },
		refunded: { label: 'Refunded', tone: 'neutral' },
		disputed: { label: 'Disputed', tone: 'warning' }
	};
</script>

<StatusBadge status="operational" />
<StatusBadge status="paid" statuses={orderStatuses} prefix="Order status:" />
<StatusBadge status="degraded" indicator="dot" pulse />

The source imports its own files by relative path only. Examples import from $lib/...; SvelteKit 3 projects have no $lib alias by default, so import from your #lib subpath (with the .svelte extension) or a relative path instead.

import type { StatusMap } from '$lib/components/status-badge-01/statuses.js';

const orderStatuses: StatusMap = {
	paid: { label: 'Paid', tone: 'success' },
	awaiting: { label: 'Awaiting payment', tone: 'info' },
	refunded: { label: 'Refunded', tone: 'neutral' },
	disputed: { label: 'Disputed', tone: 'warning' }
};

<span role="status"><StatusBadge {status} /></span>

Supply your own statuses map for labels, tones and icons. Retone with --status-badge-* variables: one per tone, and each tint and ring follows. Edit TONE_ICONS in statuses.ts to change which shape a tone uses.

• Your own states: pass statuses={{ shipped: { label: 'Shipped', tone: 'success' }, on_hold: { label: 'On hold', tone: 'warning', icon: 'clock' } }}. Keys match the values in your data exactly.
• Keep the defaults and add to them: statuses={{ ...DEFAULT_STATUSES, archived: { label: 'Archived', tone: 'neutral' } }}, importing DEFAULT_STATUSES from statuses.ts.
• Brand-aligned tones: set --status-badge-success, --status-badge-warning, --status-badge-danger and --status-badge-info on the page or an ancestor. Each label has to clear 4.5:1 against its own 8% tint, so pick a step that clears about 5:1 on white.
• Neutral tone: --status-badge-muted is its label, ring mark and tint, and --status-badge-hairline its outline.
• Dark or tinted page: set --status-badge-muted to zinc-400, --status-badge-hairline to rgb(255 255 255 / 0.12), --status-badge-surface to the page colour, and each tone to its 300 or 400 step.
• Shape: the badge is a 6 px rounded rectangle. For a pill, change rounded-md to rounded-full on the root.
• In a table: pass prefix="Order status:" so a screen reader moving cell by cell hears what the value is. Use indicator="dot" in dense rows.
• Live updates: wrap the badge in <span role="status"> when the value changes while the page is open.

Public CSS variables

• Renders a plain span with no role and no live region: a status in a table or panel is read in place, not announced. Wrap it in role="status" yourself if the value updates while the page is open.
• The label carries the meaning (WCAG 1.4.1). Each tone also has a distinct shape, so the state reads without colour, but the shape is aria-hidden and never the only signal.
• Use prefix in tables and lists where the column header is not read with the cell, so the badge reads as 'Order status: Paid' rather than 'Paid'.
• Every default tone's label clears 4.5:1 against its tint on white, zinc-50 and zinc-100 pages. Re-check if you set a tone variable.
• The pulse never runs under prefers-reduced-motion; the indicator then stands still.
• A truncated label is cut visually only; the full text stays in the DOM and is read in full.
• Not focusable and not interactive.

Known limitations

• Contrast is checked for the default colours on light pages only; retoned or dark pages are the consumer's to check.

Integration

• Presentational
• Works without client-side JavaScript
• Server-side rendering supported

Dependencies

No additional runtime packages beyond Svelte and Tailwind CSS

License

MIT. Default license approval is pending; see the license status before adopting the source.

Version history

• 1.0.0 (Published) Current release · 21 October 2026

Only the current release is available. Keep downloaded source and its receipt if you need to use it again later.