What it does
The component maps each status code to a semantic tone by extracting the hundreds-class of the number — 1xx resolves to info, 2xx to success, 3xx to redirect, 4xx to client error, 5xx to server error, and anything outside 100–599 to neutral. The tone drives the badge's background, text, and border colors across solid, soft, and outline fill variants. A built-in lookup table pairs the code with its standard reason phrase, with an override via the statusText prop for custom or uncommon codes. The component renders a single span that composes inline with other text, spreading any extra props onto the DOM element for styling or testing hooks.
Common use cases
- Annotate API responses and request logs in a debugging or admin panel.
- Show endpoint health and last-response codes in a dashboard.
- Render webhook delivery and retry status in an activity feed.
- Document expected status codes in API reference tables and developer tooling.
Composition and API
Pass a status code through the status prop. The badge derives a semantic tone from the status class and renders the code alongside a reason phrase resolved from a built-in table of common codes (200 OK, 404 Not Found, 503 Service Unavailable, and more). statusText overrides the phrase for uncommon or custom codes, showText hides the phrase to render the code on its own, appearance selects the solid, soft, or outline fill style, and size scales the padding and text. The component renders a single span and spreads any remaining props onto it, so it composes inline anywhere text or other badges live. It exports httpStatusTone and httpStatusText helpers for deriving the same tone and phrase outside the component.
Accessibility
The badge renders as a plain span carrying a data-slot attribute for styling and testing and a data-tone attribute reflecting the resolved status class, so color is never the only signal — the numeric code and reason phrase are always part of the accessible text. Because color encodes meaning, keep showText enabled (or provide your own adjacent label) wherever the tone alone would be ambiguous. Tone palettes ship light and dark variants tuned for contrast.
Next.js integration notes
HttpStatusBadge ships no framer-motion and has no animated entry — it is a static, presentational component safe to render in any Server or Client Component tree. It renders deterministically from the status prop, so server and client output match and there is no hydration mismatch. Import it from @zentauri-ui/zentauri-components/ui/http-status-badge.
FAQ
How is the tone color chosen?
The tone is derived from the status class: 1xx resolves to info, 2xx to success, 3xx to redirect, 4xx to client error, 5xx to server error, and anything outside 100–599 to neutral. You never set the color directly — pass the status code and the badge maps it for you.
Can I show a custom or unknown status code?
Yes. Any number works. Codes in the built-in table render their standard reason phrase; unknown codes fall back to the tone's human label (for example Client Error). Pass statusText to override the phrase with your own.
Can I render just the code without the reason phrase?
Set showText={false} to render only the numeric code. The tone color and data-tone attribute still apply.
Does it need framer-motion?
No. The HTTP status badge is static and presentational with no animated entry, so it ships zero framer-motion and adds no motion dependency to your bundle.
How do I theme the colors?
Override the --zui-http-status-badge-* CSS variables (per tone and fill style) on :root, a theme selector, or a wrapper. Each variable ships a light fallback and a paired -dark variant for dark mode.