Components Labels & annotation
Capsule
Keep a concise metric or status together in a pill with optional leading and trailing content.
On this page
Examples
The seed’s adoption label and decorative cobalt dot, with illustrative metric context.
Preview setting only: fitting scales this 360 px composition. Actual size preserves the copied wrapper and allows contained scrolling; it does not change component layout.
Preview only: surrounding canvas and spacing. All metrics are illustrative.
'use client';
import { Capsule } from '@coreux/ui';
export default function Default() {
return (
<figure style={{ margin: 0, boxSizing: 'border-box', width: 360, padding: 24, background: '#F4F1E9', color: '#0B1221' }}>
<Capsule primary="37% Adoption"
leading={<span aria-hidden="true" style={{ width: 10, height: 10, flexShrink: 0, borderRadius: 99, background: '#2457F5' }} />} />
<figcaption style={{ marginTop: 16, fontFamily: 'Switzer, sans-serif', fontSize: 14, lineHeight: 1.5 }}>
Illustrative adoption metric; not a measured CoreUX result.
</figcaption>
</figure>
);
}
Usage
Use Capsule for one short metric, category, or status with optional supporting content. Default, WithTrailing, and OnDark preserve the three library seeds; captions identify the numbers as illustrative. TwoLines adds a valid two-line status.
Place a small icon or dot in leading and a compact value in trailing. Those slots accept arbitrary React content but have no built-in size or content checks. Keep the primary message understandable without the dot, and include the metric’s period or baseline in nearby text.
For a display statistic with a unit and caption API, use StatBlock. For a light introductory label, use EyebrowLabel. Capsule is a static presentation and supplies no action, selection, or status announcement behavior.
Text & geometry limits
primary accepts a string or number. The renderer converts it to a string for validation: it must be non-blank and contain no more than two explicit LF or CRLF lines. There is no character limit and no finite-number validation. Prefer short copy and finite numbers.
textLines accepts exactly 1 or 2 and defaults to 1. This is a CSS line clamp, separate from the explicit-line check. Two explicit lines with textLines=1 are accepted but the second line is visually hidden. Natural wrapping also counts toward the visual clamp; do not rely on hidden text to communicate essential meaning.
The pill has a 52 px minimum height, 12 px gaps, 12 px vertical / 16 px horizontal padding, an 18 px primary font, and maxWidth: 100%. Large slots or long unbroken content can still crowd or overflow it. There is no automatic measurement or breakpoint API.
fieldMode accepts light or dark; tone accepts neutral, accent, muted, positive, warning, or error. Invalid values throw. These are the video-family appearance tokens, distinct from ink/ivory marketing tones. The component paints its own pill; the surrounding field belongs to your wrapper.
Progress props default to 1 for the completed presentation. Finite inputs clamp to 0–1; NaN and infinities throw. They are scalar controls, not an animation scheduler. Keep the settled defaults for static documentation; respect reduced-motion preferences if you animate them in an application.
Props
| Prop / type | Default | Description |
|---|---|---|
primaryRequiredstring | number | Required | Required string or number, rendered as the primary message. String(primary) must be non-blank and contain at most 2 explicit LF/CRLF lines. There is no character limit or finite-number check; use finite meaningful numbers and short text. |
leadingReactNode | undefined | Optional ReactNode rendered before the primary message, with a 12 px gap. No slot validation. Hide purely decorative icons from assistive technology; label meaningful icons. |
trailingReactNode | undefined | Optional ReactNode rendered after the primary message. No slot validation, size constraint, or automatic separator; keep it small and meaningful. A status badge is not inherently a control. |
textLines2 | 1 | 1 | Must be 1 or 2. Sets the CSS line clamp on primary text; it does not change the separate maximum of 2 explicit lines. A two-line primary with textLines=1 is accepted but visually clamped. |
fieldMode"light" | "dark" | "light" | light or dark selects the video-family appearance tokens. It does not paint the surrounding field; the copied wrapper supplies that background. |
tone"neutral" | "accent" | "muted" | "positive" | "warning" | "error" | "neutral" | neutral, accent, muted, positive, warning, or error. Changes the component surface, text, border, and/or accent according to fieldMode; unsupported values throw. Use written meaning alongside semantic colors. |
revealProgressnumber | 1 | Settled at 1. Finite values clamp to 0–1; NaN and infinities throw. Controls reveal opacity and offset. This scalar does not start an animation. |
Accessibility & layout
The pill and primary text use divs. There is no button, link, live region, or automatic ARIA label, and no general HTML-prop forwarding. Wrap it with the semantics your composition requires. The examples use figures and captions, and hide decorative dots with aria-hidden.
Keep semantic states in the written message, independently of color. Review leading/trailing content in its reading order: leading, primary, trailing. Avoid embedding controls in what looks like a simple label without deliberately designing the interaction.
The copied 360 px wrappers preserve the reviewed examples. Fit to canvas scales the entire composition; Actual size enables contained scrolling. In your application, give the pill enough real width for its text and slots and verify that the line clamp does not hide important content.
See Color for structural and semantic roles. Check contrast against the actual field and preserve written labels alongside color.
Consumer setup
Browsing, previews, and copying are public. Installing the private @coreux/ui package requires repository read access and permission to use the bundled CoreUX brand fonts.
Follow the one-time installation guide for the pinned Git dependency, Tailwind v4 stylesheet setup, fonts, and troubleshooting. Keep the 'use client' directive in each example; no provider is required.
The quick start walks through a copied StatBlock in a minimal app.
Source & revision
This reference targets @coreux/ui version 0.1.0 at 06f42fd. Types come from its installed declarations; explanations and defaults are checked against this implementation.
Revision and upgrade notes · Contribution and coverage guide
View Capsule source (repository access required)