Skip to main content

Avatar

The Avatar component displays a user's image or fallback initials. It supports sizes and shapes driven by the theme.

Import​

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

Usage​

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

function MyComponent() {
  return (
    <Avatar
      source={{ uri: 'https://example.com/user.png' }}
      size="md"
      variant="circular"
    />
  );
}

Props​

NameTypeDefaultDescription
sourceImageSourcePropType-React Native image source (e.g. { uri: string } or require(...))
labelstring-Text fallback used to render the first character when no image source is provided
size'xs' | 'sm' | 'md' | 'lg' | 'xl''md'Tokenized size controlled by the theme
variant'circular' | 'rounded' | 'square''circular'Shape of the avatar
styleStyleProp<ViewStyle>-Container style override
imageStyleStyleProp<ImageStyle>-Image style override
labelStyleStyleProp<TextStyle>-Label text style override
backgroundColorstring-Background color (overrides theme token)
textColorstring-Label color (overrides theme token)
showBorderbooleanfalseShow a border around the avatar
borderColorstring-Border color (overrides theme token)
onPress() => void-Press handler; when provided, Avatar becomes pressable
testIDstring-Test identifier

Examples​

Basic Avatars​

// Image source
<Avatar source={{ uri: 'https://example.com/u1.png' }} />

// Text fallback
<Avatar label="JD" />

Basic​

// Image source
<Avatar source={{ uri: 'https://example.com/u1.png' }} />

// Text fallback
<Avatar label="JD" />

### Avatar Sizes
```tsx
<Avatar size="xs" label="XS" />
<Avatar size="sm" label="SM" />
<Avatar size="md" label="MD" />
<Avatar size="lg" label="LG" />
<Avatar size="xl" label="XL" />

Sizes​

<Avatar size="xs" label="XS" />
<Avatar size="sm" label="SM" />
<Avatar size="md" label="MD" />
<Avatar size="lg" label="LG" />
<Avatar size="xl" label="XL" />

### Avatar Variants
```tsx
<Avatar variant="circular" label="C" />
<Avatar variant="rounded" label="R" />
<Avatar variant="square" label="S" />

Variants​

<Avatar variant="circular" label="C" />
<Avatar variant="rounded" label="R" />
<Avatar variant="square" label="S" />

### With Status
```tsx
<Stack direction="row" spacing="md">
  <Avatar
    src="/user1.jpg"
    status="online"
    alt="Online"
  />
  <Avatar
    src="/user2.jpg"
    status="busy"
    alt="Busy"
  />
  <Avatar
    src="/user3.jpg"
    status="away"
    alt="Away"
  />
  <Avatar
    src="/user4.jpg"
    status="offline"
    alt="Offline"
  />
</Stack>

Border​

<Avatar label="B" showBorder />
<Avatar label="B" showBorder borderColor="#00C853" />

Customization​

Per-instance styles​

<Avatar
  label="LP"
  backgroundColor="#222"
  textColor="#fff"
  style={{ elevation: 2 }}
  labelStyle={{ letterSpacing: 1 }}
/>

Custom Background​

<Avatar
  name="Custom"
  style={{
    background: 'linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)',
    color: 'white'
  }}
/>

Custom Border​

<Avatar
  src="/user1.jpg"
  alt="Bordered"
  bordered
  style={{
    borderColor: '#00C853',
    borderWidth: 3
  }}
/>

Custom Status Indicator​

<Avatar
  src="/user1.jpg"
  alt="Custom status"
  status="online"
  statusProps={{
    size: 12,
    color: '#00C853',
    ringColor: 'white'
  }}
/>

Theming​

Avatar styling is driven by the theme at theme.avatar.

// theme.avatar tokens
{
  sizes: { xs: 24, sm: 32, md: 40, lg: 48, xl: 56 },
  fontSizes: { xs: 12, sm: 14, md: 16, lg: 18, xl: 20 },
  background: colors.card,
  foreground: colors.text,
  borderWidth: 1,
  borderColor: colors.border,
  roundedFactor: 4,
}

Override via ThemeProvider:

import { ThemeProvider, createTheme } from '@lazy-panda-ui/lazy-panda-ui';

const customTheme = createTheme({
  avatar: {
    sizes: { md: 44 },
    fontSizes: { md: 18 },
    background: '#223',
    foreground: '#fff',
    borderColor: '#556',
    roundedFactor: 3,
  },
});

export default function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <Avatar label="LP" />
    </ThemeProvider>
  );
}

Best Practices​

  1. Provide meaningful alt text
  2. Use appropriate image sizes
  3. Handle loading states
  4. Implement proper fallbacks
  5. Consider mobile displays
  6. Use consistent sizing
  7. Optimize image assets

API Reference​

Size Values​

const avatarSizes = {
  xs: 24,
  sm: 32,
  md: 40,
  lg: 48,
  xl: 56
};

Status Colors​

const statusColors = {
  online: '#00C853',
  offline: '#9E9E9E',
  busy: '#E53935',
  away: '#FFB300'
};

Avatar Group Props​

interface AvatarGroupProps {
  max?: number;
  total?: number;
  spacing?: number | string;
  direction?: 'horizontal' | 'vertical';
  excess?: {
    background?: string;
    color?: string;
  };
}
  • Badge - For status indicators
  • Card - For user cards
  • List - For user lists