@neo4j-ndl/react/skills/ndl-react/components/avatar.md

React implementation of Neo4j Design System

# Avatar

Import: `import { Avatar } from '@neo4j-ndl/react'`

## Props

### Avatar

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `as` | `("button" & ElementType<any, keyof IntrinsicElements>) \| ("symbol" & ElementType<any, keyof IntrinsicElements>) \| ... 178 more ...` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. |
| `hasStatus` | `boolean` |  | `false` | Whether to display a status indicator |
| `icon` | `ReactNode` |  |  | Custom icon to display when `type` is `"icon"`. Defaults to `UserIconOutline` |
| `isDisabled` | `boolean` |  | `false` | Whether the avatar is disabled. When disabled, status indicators are hidden and `onClick` handlers are disabled when cast as a button |
| `name` | `string` |  |  | The name associated with the avatar. Used for alt text and aria-label. For letters type, this text is displayed |
| `onClick` | `() => void` | ✅ |  |  |
| `ref` | `any` |  |  | A ref to apply to the root element. |
| `shape` | `'circle' \| 'square'` |  | `circle` | The shape of the avatar |
| `size` | `'large' \| 'medium' \| 'small' \| 'x-large' \| 'x-small'` |  | `medium` | The size of the avatar |
| `source` | `string` |  |  | Source URI for the image. When provided with `type="image`", displays the image |
| `status` | `'offline' \| 'online' \| 'unknown'` |  |  | The status to display. Only shown when `hasStatus` is `true` and component is not disabled |
| `type` | `'icon' \| 'image' \| 'letters'` |  | `image` | The type of avatar content. If `type="image"` and no source is provided, automatically falls back to `icon` |

## Accessibility

## Implementation guidelines

The component has an `aria-label` set to `avatar ${name}` to provide context to screen readers. Status indicators include title attributes and proper role attributes. When displaying images, proper alt text is provided using the `name` prop.

## Examples

### Default

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Avatar } from '@neo4j-ndl/react';

const Component = () => {
  return <Avatar />;
};

export default Component;
```

### Custom Icon

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Avatar } from '@neo4j-ndl/react';
import {
  BellIconOutline,
  HeartIconOutline,
  StarIconOutline,
} from '@neo4j-ndl/react/icons';

const Component = () => {
  return (
    <div className="n-flex n-gap-token-16">
      <Avatar type="icon" name="Favorites" icon={<StarIconOutline />} />
      <Avatar type="icon" name="Notifications" icon={<BellIconOutline />} />
      <Avatar type="icon" name="Likes" icon={<HeartIconOutline />} />
    </div>
  );
};

export default Component;
```

### Disabled

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Avatar } from '@neo4j-ndl/react';

const Component = () => {
  return <Avatar isDisabled as="button" onClick={() => alert('Clicked!')} />;
};

export default Component;
```

### Shapes

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Avatar } from '@neo4j-ndl/react';

const Component = () => {
  return (
    <div className="n-flex n-gap-token-16">
      <Avatar shape="circle" />
      <Avatar shape="square" />
    </div>
  );
};

export default Component;
```

### Sizes

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Avatar } from '@neo4j-ndl/react';

const Component = () => {
  return (
    <div className="n-flex n-gap-token-16">
      <Avatar size="x-small" />
      <Avatar size="small" />
      <Avatar size="medium" />
      <Avatar size="large" />
      <Avatar size="x-large" />
    </div>
  );
};

export default Component;
```

### Statuses

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Avatar } from '@neo4j-ndl/react';

const Component = () => {
  return (
    <div className="n-flex n-gap-token-16 n-items-center">
      <Avatar hasStatus={false} />
      <Avatar hasStatus status="online" />
      <Avatar hasStatus status="offline" />
      <Avatar hasStatus status="unknown" />
    </div>
  );
};

export default Component;
```

### Types

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Avatar } from '@neo4j-ndl/react';

const Component = () => {
  return (
    <div className="n-flex n-gap-token-16">
      <Avatar type="icon" name="Karl Morrison" />
      <Avatar type="letters" name="Karl Morrison" />
      <Avatar
        type="image"
        name="Karl Morrison"
        source="https://media.istockphoto.com/id/1334716681/photo/a-smiling-man.jpg?s=612x612&w=0&k=20&c=U6rkSDpQMzkcJEqx2hAa63fNLIhqnZb31Xuc_QSi648="
      />
    </div>
  );
};

export default Component;
```