Skip to main content

Avatar

A picture of a person or a thing. When there's no picture, or it fails to load, it shows the initials of name instead.

Import
import { Avatar } from 'patine-ui';
Subpath
patine-ui/avatar
Source
GitHubMarkdown for LLMs
Runs on
iOSAndroidWebFree · MIT
Loading…
<VStack gap="md">
  {PEOPLE.map((person) => (
    <HStack key={person.name} gap="md" align="center">
      <Avatar name={person.name} src={person.src} />
      <VStack>
        <Text weight="medium">{person.name}</Text>
        <Text size="sm" color="textSecondary">{person.role}</Text>
      </VStack>
    </HStack>
  ))}
</VStack>

Try the props​

Props
name
src
size
shape
design
<Avatar name="Maya Cohen" />

Examples​

Each example is live: edit the code and it runs.

A team directory​

A company directory: a photo when there is one, initials when not, a presence dot in the corner, and a search that filters by name or role.

Loading…
<VStack gap="sm" style={{ width: '100%', maxWidth: 420 }}>
  <SearchField value={query} onChangeText={setQuery} placeholder="Search people" />
  <List>
    {shown.map((person) => (
      <ListItem
        key={person.name}
        title={person.name}
        description={person.role}
        accessibilityLabel={`${person.name}, ${person.role}, ${person.status}`}
        leading={
          <View>
            <Avatar name={person.name} src={'src' in person ? person.src : undefined} />
            <View style={{ position: 'absolute', right: -1, bottom: -1, width: 12, height: 12, borderRadius: 6, borderWidth: 2, borderColor: '#fff', backgroundColor: STATUS[person.status] }} />
          </View>
        }
        onPress={() => {}}
      />
    ))}
  </List>
  {shown.length ? null : <Text color="textSecondary">No one matches “{query}”.</Text>}
</VStack>

Sizes and shapes​

size is sm (32), md (40), lg (56) or a number of points. shape="square" rounds the corners instead, for teams and companies.

Loading…
<HStack gap="md" align="center">
  <Avatar name="Ana Silva" size="sm" />
  <Avatar name="Ana Silva" />
  <Avatar name="Ana Silva" size="lg" />
  <Avatar name="Acme Inc" size={72} shape="square" />
</HStack>

Fallback​

With no src, or one that fails to load, the avatar shows the first letters of the first and last words of name. With no name either, it shows a blank circle.

Loading…
<HStack gap="md" align="center">
  <Avatar name="Maya Cohen" src="https://picsum.photos/id/64/160/160" />
  <Avatar name="Maya Cohen" />
  <Avatar name="Broken Link" src="https://invalid.example/404.png" />
  <Avatar name="Prince" />
  <Avatar />
</HStack>

Who's online​

Wrap it in a View to pin a status dot or a count to its corner.

Loading…
<HStack gap="lg" align="center">
  <View accessibilityLabel="Maya Cohen, online">
    <Avatar size="lg" name="Maya Cohen" src="https://picsum.photos/id/64/160/160" />
    <Dot color="#22C55E" />
  </View>
  <View accessibilityLabel="Leo Martin, away">
    <Avatar size="lg" name="Leo Martin" src="https://picsum.photos/id/1005/160/160" />
    <Dot color="#F59E0B" />
  </View>
  <View accessibilityLabel="Ana Silva, offline">
    <Avatar size="lg" name="Ana Silva" />
    <Dot color="#9CA3AF" />
  </View>
</HStack>

Who's editing​

Overlap avatars with a negative margin and a ring in the background color, and end with a count of the rest.

Loading…
<HStack align="center" gap="md">
  <HStack accessibilityLabel={`${MEMBERS.length} members`} accessible>
    {MEMBERS.slice(0, SHOWN).map((name, i) => (
      <View key={name} style={[ring, { marginLeft: i ? -12 : 0 }]}>
        <Avatar name={name} />
      </View>
    ))}
    <View style={[ring, { marginLeft: -12, width: 44, height: 44, alignItems: 'center', justifyContent: 'center', backgroundColor: colors.surface }]}>
      <Text size="sm" weight="medium">+{MEMBERS.length - SHOWN}</Text>
    </View>
  </HStack>
  <Text color="textSecondary">Maya, Leo and 5 others are editing</Text>
</HStack>

Workspaces in a switcher​

shape="square" rounds the corners instead of a circle, the usual sign of an organization rather than a person.

Loading…
<VStack gap="md">
  {WORKSPACES.map((w) => (
    <HStack key={w.name} gap="md" align="center">
      <Avatar name={w.name} shape="square" />
      <Text weight="medium" style={{ flex: 1 }}>{w.name}</Text>
      <Badge variant={w.plan === 'Pro' ? 'default' : 'secondary'}>{w.plan}</Badge>
    </HStack>
  ))}
</VStack>

In real apps​

Patine Pro screens built with it. Each opens on that screen, live, in the screens gallery.

Guidelines​

Do

Always pass name. It's the fallback initials and what a screen reader says.

Don’t

Don't leave a broken picture blank. Without name, a failed image is an empty circle.

Do

Round people, square organizations. The shape tells a person from a team at a glance.

(green dot only)
Don’t

Don't rely on the dot's color for status. Write the status in the label or next to the name too.

Accessibility​

Behaviour
RoleAn image named by name, so a screen reader reads the name once, not the initials.
AnnouncedNone.
Keyboard (web)Not focusable on its own; wrap it in a pressable to make it a button.
Touch targetOnly matters when it's pressable: md (40) and up, or give the pressable hitSlop.
Reduce motionNothing moves.
  • Leave name out for a purely decorative picture next to a name that's already written.

API​

Avatar​

PropTypeDefaultDescription
srcstring | ImageSourcePropType—The picture. Falls back to initials when missing or broken.
namestring—Read by screen readers, and the initials when there's no picture.
size'sm' | 'md' | 'lg' | number'md'32, 40 or 56 points, or any number.
shape'circle' | 'square''circle'Round, or rounded corners.
styleStyleProp<ViewStyle>—The avatar's box.
themeDeepPartial<Theme>—Theme override.
design'brand' | 'ios' | 'material' | 'web' | 'native'from PatineProviderThe look to follow: brand, iOS, Material or web, or 'native' for the platform's own.

Right to left and custom styles work the same on every component: see Internationalization and right to left and Styling.

For AI​

Give this page to an assistant as Markdown, with Copy page at the top, or the whole API in llms-full.txt.

With the Patine MCP server, it asks for get_component_docs({ name: "Avatar" })