# Avatar (React Native)

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

GramproKit for React Native · Display · Beta · Source: https://kit.gramproindia.com/native/docs/avatar

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

_Interactive demo:_ [open the live example](https://kit.gramproindia.com/native/docs/avatar). The example's source:

```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

```bash
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

| Prop | Type | Description |
|---|---|---|
| `name` | `string` | The person or thing: the accessible name, the initials and the colour. |
| `src` | `string` | The image. If it fails to load, the avatar falls back to the initials. |
| `initials` | `string` | Overrides the text derived from `name`. |
| `children` | `ReactNode` | An icon or anything else to show instead of initials. |
| `size` | `AvatarSize` | Default `md` (32dp). |
| `shape` | `AvatarShape` | Default `circle`. |
| `status` | `AvatarStatus` | A presence dot in the corner. |
| `decorative` | `boolean` | Marks the avatar as decoration, for a name printed next to it. |
| `style` | `StyleProp<ViewStyle>` |   |
| `styles` | `Partial<{ root: StyleProp<ViewStyle>; image: StyleProp<ImageStyle>; fallback: StyleProp…` |   |
| `localeText` | `Partial<AvatarLocaleText>` |   |

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

### AvatarGroupProps

| Prop | Type | Description |
|---|---|---|
| `children` (required) | `ReactNode` |   |
| `max` | `number` | How many slots there are, the overflow bubble included. Default 4. |
| `size` | `AvatarSize` | Applied to the group; each Avatar keeps its own if it sets one. |
| `shape` | `AvatarShape` |   |
| `label` | `string` | Names the set, e.g. "Assigned to". |
| `style` | `StyleProp<ViewStyle>` |   |
| `styles` | `Partial<{ root: StyleProp<ViewStyle>; overflow: StyleProp<ViewStyle> }>` |   |
| `localeText` | `Partial<AvatarLocaleText>` |   |

## Native and web

- Initials are grapheme-aware even without `Intl.Segmenter` (Hermes): അര, 👨‍👩‍👧 stay whole.
- Web version: [Avatar on the web](https://kit.gramproindia.com/avatar).