Badge

The Badge component is used as an adornment to other elements, typically displaying a count, status, or short notification.

Installation

$ cbui-cli install @crossbuildui/badge

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { Badge } from '@/crossbuildui/badge';
// import Icon from 'react-native-vector-icons/MaterialCommunityIcons'; // If using icons in badge content
// import { View, Text } from 'react-native'; // For children elements

The Badge component uses react-native-reanimated for animations. Ensure this library is installed and configured in your Expo project.

Basic Usage

Wrap any component with Badge and provide content. Use isDot for a simple dot indicator.

index.tsx

// Basic badge with text content
<Badge content="NEW">
  <Button>My Button</Button>
</Badge>

// Badge with numerical content
<Badge content={5} color="primary">
  <View style={{width: 50, height: 50, backgroundColor: 'lightgrey'}} />
</Badge>

// Dot badge
<Badge isDot color="success">
  <Text>Notifications</Text>
</Badge>

Variants & Colors

Badges support solid (default), flat, faded, and shadow variants. Apply thematic colors using the color prop.

index.tsx

// Solid (default)
<Badge content="S" color="primary">
  <View style={{width: 40, height: 40, backgroundColor: 'aliceblue'}} />
</Badge>

// Flat
<Badge content="F" variant="flat" color="secondary">
  <View style={{width: 40, height: 40, backgroundColor: 'aliceblue'}} />
</Badge>

// Faded
<Badge content="Fd" variant="faded" color="success">
  <View style={{width: 40, height: 40, backgroundColor: 'aliceblue'}} />
</Badge>

// Shadow
<Badge content="Sh" variant="shadow" color="warning">
  <View style={{width: 40, height: 40, backgroundColor: 'aliceblue'}} />
</Badge>

Sizes

Adjust badge size with sm, md (default), or lg. This also affects dot size.

index.tsx

<Badge content="Small" size="sm" color="danger">
  <Text>SM</Text>
</Badge>

<Badge content="Medium" size="md" color="primary">
  <Text>MD</Text>
</Badge>

<Badge content="Large" size="lg" color="success">
  <Text>LG</Text>
</Badge>

// Dot sizes
<Badge isDot size="sm"><View style={{width:20, height:20, backgroundColor:'lightgray'}}/></Badge>
<Badge isDot size="md"><View style={{width:20, height:20, backgroundColor:'lightgray'}}/></Badge>
<Badge isDot size="lg"><View style={{width:20, height:20, backgroundColor:'lightgray'}}/></Badge>

Shapes

Badges can be rectangle or circle. The shape defaults to circle for dots (isDot) or single characters (isOneChar or auto-detected).

index.tsx

// Rectangle (default for multi-char or custom content)
<Badge content="Sale" shape="rectangle" color="primary">
  <Text>Item</Text>
</Badge>

// Circle (default for single char, isDot, or explicit)
<Badge content="1" shape="circle" color="secondary">
  <Text>Msg</Text>
</Badge>

// isOneChar prop for single character content to enforce circle
<Badge content="A" isOneChar color="success">
  <Text>User</Text>
</Badge>

// isDot prop (always circle)
<Badge isDot color="warning">
  <Text>Status</Text>
</Badge>

Placement

Position the badge relative to its child using placement: top-right (default), top-left, bottom-right, bottom-left.

index.tsx

<View style={{ flexDirection: 'row', justifyContent: 'space-around', width: '100%', padding: 20 }}>
  <Badge content="TR" placement="top-right"><View style={styles.box} /></Badge>
  <Badge content="TL" placement="top-left"><View style={styles.box} /></Badge>
  <Badge content="BR" placement="bottom-right"><View style={styles.box} /></Badge>
  <Badge content="BL" placement="bottom-left"><View style={styles.box} /></Badge>
</View>

// styles.box: { width: 50, height: 50, backgroundColor: 'lightgrey' }

Max Count

Use maxCount to cap numerical content (e.g., 99+).

index.tsx

<Badge content={100} maxCount={99} color="primary">
  <Text>Notifications</Text>
</Badge>

<Badge content={50} maxCount={99} color="secondary">
  <Text>Messages</Text>
</Badge>

Custom Content

The content prop can accept any ReactNode, allowing for icons or custom components within the badge.

index.tsx

const CustomBadgeIcon = () => <Icon name="star" size={12} color="white" />;

<Badge content={<CustomBadgeIcon />} color="warning" shape="circle">
  <Button>Featured</Button>
</Badge>

Visibility & Animation

Control visibility with isInvisible and toggle animations with disableAnimation.

index.tsx

// Invisible badge
<Badge content="Hidden" isInvisible>
  <Text>This badge is not visible.</Text>
</Badge>

// Badge with animation disabled
<Badge content="No Anim" disableAnimation color="success">
  <Text>This badge appears/disappears instantly.</Text>
</Badge>

Outline

The showOutline prop (default true) adds a contrasting border around the badge.

index.tsx

<Badge content="Outline" color="primary" showOutline={true}>
  <Text>Item A</Text>
</Badge>

<Badge content="No Outline" color="secondary" showOutline={false}>
  <Text>Item B</Text>
</Badge>

Props Overview

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode`	-	The component the badge adorns.
`content`	`string \| number \| ReactNode`	-	Content inside the badge. Ignored if `isDot` is true.
`variant`	`'solid' \| 'flat' \| 'faded' \| 'shadow'`	`'solid'`	Visual style.
`color`	`BadgeColor`	`'default'`	Semantic color.
`size`	`BadgeSize`	`'md'`	Size of the badge.
`shape`	`BadgeShape`	`'rectangle'`	Shape of the badge (or `'circle'` for dots/single char).
`placement`	`BadgePlacement`	`'top-right'`	Position relative to children.
`showOutline`	`boolean`	`true`	Show contrasting outline.
`disableAnimation`	`boolean`	`false`	Disable enter/exit animations.
`isInvisible`	`boolean`	`false`	Hide the badge.
`isOneChar`	`boolean`	`false`	Hint for circular shape with single char content.
`isDot`	`boolean`	`false`	Render as a small dot, ignores content.
`style`	`StyleProp<ViewStyle>`	-	Style for the badge's outer wrapper (Badge + Children).
`badgeStyle`	`StyleProp<ViewStyle>`	-	Custom style for the badge element itself.
`textStyle`	`StyleProp<TextStyle>`	-	Custom style for text content within the badge.
`maxCount`	`number`	99	Max number to show before displaying `maxCount+`.

Styling

Customize the appearance using:

style: Applied to the root View that wraps both the children and the badge itself. Useful for positioning the entire unit.
badgeStyle: Applied directly to the Animated.View that renders the badge. Use this for badge-specific styles like background, border, dimensions (though size prop is preferred for dimensions).
textStyle: Applied to the Text component inside the badge if the content is a string or number.

index.tsx

<Badge
  content="Styled"
  color="primary"
  style={{ margin: 10 }} // Styles the outer View container (Badge + Children)
  badgeStyle={{
    borderWidth: 2,
    borderColor: 'darkblue',
    transform: [{ rotate: '-5deg' }]
  }}
  textStyle={{
    fontStyle: 'italic',
    textDecorationLine: 'underline'
  }}
>
  <View style={{padding: 10, backgroundColor: 'lightyellow'}}>
    <Text>Content Here</Text>
  </View>
</Badge>

Accessibility

The Badge component itself is primarily decorative. Accessibility considerations depend on its context and content:

If the badge content conveys important information (e.g., "3 new messages"), ensure this information is also available to assistive technologies through the parent component it adorns. For example, an icon button with a badge might have an accessibilityLabel like "Notifications, 3 unread".
For purely decorative badges (e.g., a status dot that's visually explained elsewhere), no specific accessibility props might be needed on the badge itself.
The badge text will be read by screen readers if it's a string or number. If using custom ReactNode content, ensure that node is accessible.

Avatar Card

Badge

Installation

Import

Basic Usage

Variants & Colors

Sizes

Shapes

Placement

Max Count

Custom Content

Visibility & Animation

Outline

Props Overview

Styling

Accessibility

Badge on Avatar

Badge with custom icon

Badge Content

Badge Variants