All components
Data Display
BadgeGroup
stable
Since 1.2
A badge paired with descriptive text in one pill — for announcements and callouts, with leading or trailing placement and an optional action.
Data Display
primitive
Display
Documented
import { BadgeGroup } from '@ivim/native/components';
When to use
Use when
Announcing something new, where a short tag and a sentence belong together.
Pairing a status with the detail that explains it.
Don't use when
The label stands alone — use Badge.
The message needs a heading, body, and actions — use Banner or Callout.
Playground
Adjust the controls to preview live prop combinations. The code snippet updates to match the current selection.
New
Dashboards have shipped
tone
tone
neutral
brand
success
warning
error
info
placement
placement
leading
trailing
variant
variant
pill
modern
Badge
label
<BadgeGroup label="New" />
Example
Preview
Code
Treatments
Default (pill)
New
Dashboards have shipped
Modern, on a tinted surface
New
Dashboards have shipped
Trailing placement
Try the new editor
Beta
Tones and sizes
Tones
New
Dashboards have shipped
Fixed
Sync no longer drops records
Deprecated
The v1 API retires in March
Medium size
New
Dashboards have shipped
Actions
Actionable (announced as one sentence)
Long text wraps rather than clipping
Note
This description is deliberately long so the pill has to wrap at larger text scales instead of truncating.
Anatomy
The parts that compose this component.
1
Container
Pill carrying the surface, border, and radius.
2
Badge
The emphasized label, in any Badge tone.
3
Text
The descriptive phrase beside it.
Guidelines
Do
Keep the badge to one word and let the text carry the sentence.
Do
Use the modern treatment on tinted surfaces, where the default fill would disappear.
Don't
Add onPress without somewhere meaningful to go — the whole pill becomes one button.
Props
Public props for this component. Required props are marked; defaults reflect the component implementation.
label
required
string
The emphasized badge text.
children
required
ReactNode
The descriptive phrase beside the badge.
tone
BadgeTone
default: 'neutral'
Badge tone, shared with Badge.
placement
'leading' | 'trailing'
default: 'leading'
Which side the badge sits on.
variant
'pill' | 'modern'
default: 'pill'
Tinted surface, or a neutral one with a hairline.
size
'sm' | 'md'
default: 'sm'
Badge and text scale.
onPress
() => void
Makes the whole pill one named button.
aria-label
string
Accessible name when there is no visible label, or when the label is not plain text.
Accessibility
Roles and screen-reader behavior this component provides, plus keyboard interactions.
•
When actionable, the badge and text are announced as one name ("New: Dashboards have shipped") rather than two fragments.
•
Without onPress no role is applied, so a decorative callout is not announced as a control.
•
The pill wraps rather than clipping, so long text stays readable at large text scales.
Tab
Reaches the pill only when it is actionable.
Space / Enter
Activates it.
Platform & RTL
Behavior that differs across the platforms this component runs on.
Web
An actionable pill gets an inset focus ring matched to its radius.
iOS
Press feedback from PressableFeedback when actionable.
Android
Adds a ripple when actionable.
RTL
Leading and trailing placement mirror with the writing direction.
State coverage
Interaction and visual states this component supports.
base
semantic color
density
Token references
Semantic design tokens this component page exercises. Tap one to edit it live.
Related components
Components that solve adjacent problems or compose with this one.
Badge
Compact status or metadata label with six semantic tones plus seven non-semantic accent tones, four treatments, a pill or square shape, three sizes, dots, counts, adornments, and optional press and remove actions.
TagGroup
A row of tags: static labels, or single/multiple selection, with per-tag and group removal, dots, counts, and avatar slots.
InlineCta
Compact in-content call-to-action with title, description, optional media, and a trailing action.
Banner
Full-width status banner for page-level messages and optional actions.