Skip to content
React NativeBeta

Avatar

Pictures, initials in any script, status dots and overlapping groups.

Beta. React Native support is in beta. APIs may change or break between prereleases (npm tag native).

On this page
Web preview — real device may differ
tsx
import { Text } from "react-native";
import { Avatar, AvatarGroup } from "@/component-lib/avatar";
import { Row, Section } from "./layout"; // Section and Row: page layout for the demo
 
const PEOPLE = ["Anand Remanan", "Ada Lovelace", "Grace Hopper", "അനന്തു രമണൻ", "Linus Torvalds", "Margaret Hamilton"];
 
export function AvatarDemo() {
  return (
    <>
      <Section title="Avatar · sizes and shapes">
        <Row>
          {(["xs", "sm", "md", "lg", "xl"] as const).map((size) => (
            <Avatar key={size} size={size} name="Anand Remanan" />
          ))}
        </Row>
        <Row>
          {(["xs", "sm", "md", "lg", "xl"] as const).map((size) => (
            <Avatar key={size} size={size} shape="square" name="Grace Hopper" />
          ))}
        </Row>
      </Section>
 
      <Section title="Avatar · names, image, status">
        <Row>
          {PEOPLE.map((name) => (
            <Avatar key={name} size="lg" name={name} />
          ))}
          <Avatar size="lg" name="👨‍👩‍👧 Family" />
        </Row>
        <Row>
          <Avatar size="lg" name="Picsum" src="https://picsum.photos/id/64/120" status="online" />
          <Avatar size="lg" name="Broken Image" src="https://invalid.example/nope.png" status="away" />
          <Avatar size="lg" name="Busy Bee" status="busy" />
          <Avatar size="lg" shape="square" name="Off Line" status="offline" />
          <Avatar size="lg" name="Icon">
            <Text style={{ fontSize: 18 }}>★</Text>
          </Avatar>
        </Row>
      </Section>
 
      <Section title="AvatarGroup">
        <AvatarGroup label="Assigned to" max={4}>
          {PEOPLE.map((name) => (
            <Avatar key={name} name={name} />
          ))}
        </AvatarGroup>
        <AvatarGroup label="Reviewers" size="lg" shape="square" max={3}>
          {PEOPLE.slice(0, 5).map((name) => (
            <Avatar key={name} name={name} />
          ))}
        </AvatarGroup>
        <AvatarGroup label="Two people" size="sm">
          <Avatar name="Ada Lovelace" />
          <Avatar name="Grace Hopper" />
        </AvatarGroup>
      </Section>
    </>
  );
}

Install

npx @grampro/kit@native add Avatar

Usage

tsx
import { Avatar, AvatarGroup } from "@/component-lib/avatar";
 
<Avatar name="Anand Remanan" status="online" />
<AvatarGroup max={3}>{people.map((p) => <Avatar key={p.id} name={p.name} src={p.photo} />)}</AvatarGroup>

Props

AvatarProps

PropTypeDescription
namestringThe person or thing: the accessible name, the initials and the colour.
srcstringThe image. If it fails to load, the avatar falls back to the initials.
initialsstringOverrides the text derived from name.
childrenReactNodeAn icon or anything else to show instead of initials.
sizeAvatarSizeDefault md (32dp).
shapeAvatarShapeDefault circle.
statusAvatarStatusA presence dot in the corner.
decorativebooleanMarks the avatar as decoration, for a name printed next to it.
styleStyleProp<ViewStyle>
stylesPartial<{ root: StyleProp<ViewStyle>; image: StyleProp<ImageStyle>; fallback: StyleProp…
localeTextPartial<AvatarLocaleText>

Also accepts the props of Omit<ViewProps, "children" | "style">.

AvatarGroupProps

PropTypeDescription
children (required)ReactNode
maxnumberHow many slots there are, the overflow bubble included. Default 4.
sizeAvatarSizeApplied to the group; each Avatar keeps its own if it sets one.
shapeAvatarShape
labelstringNames the set, e.g. "Assigned to".
styleStyleProp<ViewStyle>
stylesPartial<{ root: StyleProp<ViewStyle>; overflow: StyleProp<ViewStyle> }>
localeTextPartial<AvatarLocaleText>

Native and web

  • Initials are grapheme-aware even without Intl.Segmenter (Hermes): അര, 👨‍👩‍👧 stay whole.
  • Web version: Avatar on the web.