Badge

Installation

$ npx shadcn@latest add https://goodui.dev/native/r/badge.json

Then run npx expo install --fix so react-native-reanimated match your Expo SDK. Files land in components/goodui-native/badge.

Usage

import { View } from "react-native";
import { Text } from "@/components/goodui-native/foundation";
import { Badge, BadgeAnchor } from "@/components/goodui-native/badge/badge";

export function InboxRow({ unread, avatar }: { unread: number; avatar: React.ReactNode }) {
  return (
    <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
      <BadgeAnchor dot pulse tone="success" overlap="circular" placement="bottom-right" accessibilityLabel="Online">
        {avatar}
      </BadgeAnchor>
      <Text style={{ flex: 1 }}>Design team</Text>
      <Badge count={unread} />
    </View>
  );
}

When to use

Examples

<Badge count={3} />
<Badge count={128} />            // "99+"
<Badge count={1200} max={999} /> // "999+"
<Badge count={0} />              // hidden; shrinks away when it reaches 0
<Badge count={0} showZero tone="neutral" variant="soft" />

<Badge label="New" tone="accent" variant="soft" />
<Badge label="Live" dot pulse tone="danger" variant="soft" />
<Badge label="Overdue" tone="warning" variant="outline" size="sm" />

<BadgeAnchor count={unread} ring="background">
  <BellIcon />
</BadgeAnchor>

API reference

Motion and haptics

• •Appears with the bouncy spring from zero scale; at zero (or when its content goes away) it shrinks out with a fast timing, then unmounts.
• •A changed count or label pops: a quick swell to 1.3, then the bouncy spring back.
• •`pulse` sends a ring outward from the dot every 1.4 s, for live and online states.
• •Reduced motion: no pop, no scale and no pulse; the badge fades in and out.

• •Haptic: None: a badge reports a change, it does not confirm an action.

• •All animation runs on the UI thread. React renders only when the count, label or visibility changes.
• •BadgeAnchor measures its child once per real size change (for circular overlap) and never re-lays it out.

Accessibility

• •Read as text: the label, the count, or 'More than 99' past the cap; override with accessibilityLabel.
• •Pass `decorative` when the element it belongs to already says the count, so it is not read twice.
• •The badge never takes touches; BadgeAnchor's child keeps its own role and label.
• •Status meaning never relies on color alone: pair a tone with a label or with the anchored element's label.
• •On the web a badge is role img named by its label, and a decorative badge is aria-hidden.

Notes for AI

Related