Badge

The Badge component highlights counts or status, standalone or decorating another component.

Import

import { Badge } from '@lazy-panda-ui/lazy-panda-ui';

Usage

import React from 'react';
import { Badge } from '@lazy-panda-ui/lazy-panda-ui';

function MyComponent() {
  return (
    <Badge value={3}>
      <Icon name="notification" />
    </Badge>
  );
}

Props

Name	Type	Default	Description
value	string | number	0	Value to display in badge (hidden when 0 unless showZero)
variant	'filled' | 'outlined' | 'dot' | 'tonal'	'filled'	Visual style
color	'primary' | 'secondary' | 'error' | 'warning' | 'success' | 'info'	'primary'	Color scheme
size	'small' | 'medium' | 'large'	'medium'	Size token
max	number	99	If value exceeds, displays max+
showZero	boolean	false	Whether to show when value is 0
style	StyleProp<ViewStyle>	-	Container style override
textStyle	StyleProp<TextStyle>	-	Text style override
children	React.ReactNode	-	Optional content to decorate
position	'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'	'top-right'	Position relative to children
alignment	'inside' | 'outside'	'outside'	Place badge within or outside child bounds
showPulse	boolean	false	Pulse animation
visible	boolean	true	Toggles visibility
onPress	() => void	-	Press handler
testID	string	-	Test identifier

Examples

Basic

<Stack direction="row" spacing="lg">
  <Badge value={4}>
    <Icon name="mail" />
  </Badge>
  <Badge variant="dot">
    <Icon name="notification" />
  </Badge>
</Stack>

Badge Colors

<Stack direction="row" spacing="lg">
  <Badge value={1} color="primary">
    <Box>Primary</Box>
  </Badge>
  <Badge value={2} color="secondary">
    <Box>Secondary</Box>
  </Badge>
  <Badge value={3} color="success">
    <Box>Success</Box>
  </Badge>
  <Badge value={4} color="warning">
    <Box>Warning</Box>
  </Badge>
  <Badge value={5} color="error">
    <Box>Error</Box>
  </Badge>
</Stack>

Badge Variants

<Stack direction="row" spacing="lg">
  <Badge variant="filled" value={99}>
    <Avatar />
  </Badge>
  <Badge variant="dot" color="success">
    <Avatar />
  </Badge>
  <Badge variant="outlined" value={12}>
    <Avatar />
  </Badge>
  <Badge variant="tonal" value={8} color="secondary">
    <Avatar />
  </Badge>
</Stack>

Maximum Value

<Stack direction="row" spacing="lg">
  <Badge value={100} max={99}>
    <Icon name="inbox" />
  </Badge>
  <Badge value={1000} max={999}>
    <Icon name="message" />
  </Badge>
</Stack>

Positioning

Horizontal and Vertical

<Stack direction="row" spacing="lg">
  <Badge value={4} position="top-right">
    <Box>Top Right</Box>
  </Badge>
  <Badge value={4} position="top-left">
    <Box>Top Left</Box>
  </Badge>
  <Badge value={4} position="bottom-right">
    <Box>Bottom Right</Box>
  </Badge>
</Stack>

Overlap Styles

<Stack direction="row" spacing="lg">
  <Badge value={4} alignment="inside">
    <Avatar />
  </Badge>
  <Badge value={4} alignment="outside">
    <Box>Rectangle</Box>
  </Badge>
</Stack>

Customization

Custom Content

<Badge value={5}>
  <Avatar />
</Badge>

Custom Styles

<Badge
  value={5}
  style={{
    backgroundColor: '#FF6B6B',
    paddingHorizontal: 8,
    height: 24,
    minWidth: 24,
    borderRadius: 16,
  }}
>
  <Box>Custom Badge</Box>
</Badge>

Dynamic Visibility

<Badge
  value={messageCount}
  visible={messageCount !== 0}
>
  <Icon name="mail" />
</Badge>

Accessibility

Note: ARIA attributes are web-only; for React Native, use testID and accessible props on parents.

Best Practices

1. Use clear and concise content
2. Choose appropriate colors for context
3. Consider maximum values for clarity
4. Use consistent positioning
5. Handle zero states appropriately
6. Maintain readability
7. Include proper ARIA attributes

API Reference

Badge Placement

interface BadgePlacement {
  horizontal: 'left' | 'right';
  vertical: 'top' | 'bottom';
  offset?: {
    x?: number;
    y?: number;
  };
}

Theming

Badge size/typography/border are driven by theme.badge tokens.

badge: {
  sizes: {
    small: { height: 16, minWidth: 16, dot: 8, paddingX: 4 },
    medium: { height: 20, minWidth: 20, dot: 10, paddingX: 6 },
    large: { height: 24, minWidth: 24, dot: 12, paddingX: 8 },
  },
  fontSizes: { small: 10, medium: 12, large: 14 },
  borderWidth: 1,
}

Related Components

• Avatar - For user avatars
• Icon - For icons
• Chip - For status and selections
• Button - For actions with badges