> ## Documentation Index
> Fetch the complete documentation index at: https://araf.badr.co.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Avatar

> A visual representation of a user or entity — supports images, initials fallback, status indicators, sizes, shapes, and grouped stacks.

## Overview

<div style={{display:"flex",gap:"20px",flexWrap:"wrap",padding:"28px 24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb",alignItems:"center"}}>
  {[["XS","20px","8px"],["SM","28px","10px"],["MD","36px","12px"],["LG","48px","14px"],["XL","64px","18px"]].map(([label, size, fontSize]) => (
      <div key={label} style={{display:"flex",flexDirection:"column",alignItems:"center",gap:"8px"}}>
        <div style={{width:size,height:size,borderRadius:"50%",background:"#0479CE",display:"flex",alignItems:"center",justifyContent:"center",flexShrink:0}}>
          <span style={{color:"#fff",fontSize:fontSize,fontWeight:600,fontFamily:"Inter,sans-serif"}}>{label}</span>
        </div>
        <span style={{fontSize:"11px",color:"#71717a",fontFamily:"Inter,sans-serif"}}>{label}</span>
      </div>
    ))}

  <div style={{display:"flex",flexDirection:"column",alignItems:"center",gap:"8px",marginLeft:"16px"}}>
    <div style={{position:"relative",width:"36px",height:"36px"}}>
      <div style={{width:"36px",height:"36px",borderRadius:"50%",background:"#16A34A",display:"flex",alignItems:"center",justifyContent:"center"}}>
        <span style={{color:"#fff",fontSize:"12px",fontWeight:600,fontFamily:"Inter,sans-serif"}}>AD</span>
      </div>

      <div style={{position:"absolute",bottom:"0px",right:"0px",width:"10px",height:"10px",borderRadius:"50%",background:"#16A34A",border:"2px solid #fff"}} />
    </div>

    <span style={{fontSize:"11px",color:"#71717a",fontFamily:"Inter,sans-serif"}}>Online</span>
  </div>

  <div style={{display:"flex",flexDirection:"column",alignItems:"center",gap:"8px"}}>
    <div style={{position:"relative",width:"36px",height:"36px"}}>
      <div style={{width:"36px",height:"36px",borderRadius:"50%",background:"#EAB308",display:"flex",alignItems:"center",justifyContent:"center"}}>
        <span style={{color:"#fff",fontSize:"12px",fontWeight:600,fontFamily:"Inter,sans-serif"}}>RM</span>
      </div>

      <div style={{position:"absolute",bottom:"0px",right:"0px",width:"10px",height:"10px",borderRadius:"50%",background:"#EAB308",border:"2px solid #fff"}} />
    </div>

    <span style={{fontSize:"11px",color:"#71717a",fontFamily:"Inter,sans-serif"}}>Away</span>
  </div>

  <div style={{display:"flex",alignItems:"center",gap:"0",marginLeft:"16px"}}>
    {["A1","A2","A3","A4"].map((init, i) => (
            <div key={init} style={{width:"32px",height:"32px",borderRadius:"50%",border:"2px solid #fff",background:`hsl(${i*40+200},70%,55%)`,display:"flex",alignItems:"center",justifyContent:"center",marginLeft:i>0?"-8px":"0",zIndex:4-i}}>
              <span style={{color:"#fff",fontSize:"10px",fontWeight:600,fontFamily:"Inter,sans-serif"}}>{init}</span>
            </div>
          ))}

    <div style={{width:"32px",height:"32px",borderRadius:"50%",border:"2px solid #fff",background:"#E4E4E7",display:"flex",alignItems:"center",justifyContent:"center",marginLeft:"-8px"}}>
      <span style={{color:"#52525B",fontSize:"10px",fontWeight:600,fontFamily:"Inter,sans-serif"}}>+2</span>
    </div>
  </div>
</div>

**Avatar** displays a user's profile image or their initials when no image is available. It supports five sizes, circle and square shapes, status indicators, and grouped stacks.

***

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @araf-ds/core
  ```

  ```bash yarn theme={null}
  yarn add @araf-ds/core
  ```

  ```bash pnpm theme={null}
  pnpm add @araf-ds/core
  ```
</CodeGroup>

***

## Usage

```tsx theme={null}
import { Avatar, AvatarGroup } from "@araf-ds/core"

export default function Example() {
  return (
    <Avatar
      src="/photo.jpg"
      fallback="AD"
      size="md"
      status="online"
    />
  )
}
```

***

## Variants

### Sizes

<div style={{padding:"24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb"}}>
  <div style={{display:"flex",gap:"16px",alignItems:"center",flexWrap:"wrap"}}>
    {[["XS","20px","8px"],["SM","28px","10px"],["MD","36px","12px"],["LG","48px","14px"],["XL","64px","18px"]].map(([label, size, fontSize]) => (
            <div key={label} style={{display:"flex",flexDirection:"column",alignItems:"center",gap:"6px"}}>
              <div style={{width:size,height:size,borderRadius:"50%",background:"#0479CE",display:"flex",alignItems:"center",justifyContent:"center"}}>
                <span style={{color:"#fff",fontSize:fontSize,fontWeight:600,fontFamily:"Inter,sans-serif"}}>{label}</span>
              </div>
              <span style={{fontSize:"11px",color:"#71717a",fontFamily:"Inter,sans-serif"}}>{label}</span>
            </div>
          ))}
  </div>
</div>

```tsx theme={null}
<Avatar size="xs" fallback="AD" />
<Avatar size="sm" fallback="AD" />
<Avatar size="md" fallback="AD" />
<Avatar size="lg" fallback="AD" />
<Avatar size="xl" fallback="AD" />
```

| Size | Diameter | Use case                    |
| ---- | -------- | --------------------------- |
| `xs` | 20px     | Dense lists, tables         |
| `sm` | 28px     | Compact cards               |
| `md` | 36px     | Default — sidebars, headers |
| `lg` | 48px     | Profile sections            |
| `xl` | 64px     | Full profile pages          |

### With Status Indicator

<div style={{padding:"24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb"}}>
  <div style={{display:"flex",gap:"16px",alignItems:"center"}}>
    {[["AD","#16A34A","Online"],["RM","#EAB308","Away"],["JS","#EF4444","Busy"],["ZK","#9CA3AF","Offline"]].map(([init, color, label]) => (
            <div key={label} style={{display:"flex",flexDirection:"column",alignItems:"center",gap:"6px"}}>
              <div style={{position:"relative",width:"36px",height:"36px"}}>
                <div style={{width:"36px",height:"36px",borderRadius:"50%",background:"#E4E4E7",display:"flex",alignItems:"center",justifyContent:"center"}}>
                  <span style={{color:"#52525B",fontSize:"12px",fontWeight:600,fontFamily:"Inter,sans-serif"}}>{init}</span>
                </div>
                <div style={{position:"absolute",bottom:"0",right:"0",width:"10px",height:"10px",borderRadius:"50%",background:color,border:"2px solid #fff"}}/>
              </div>
              <span style={{fontSize:"11px",color:"#71717a",fontFamily:"Inter,sans-serif"}}>{label}</span>
            </div>
          ))}
  </div>
</div>

```tsx theme={null}
<Avatar fallback="AD" size="md" status="online" />
<Avatar fallback="RM" size="md" status="away" />
<Avatar fallback="JS" size="md" status="busy" />
<Avatar fallback="ZK" size="md" status="offline" />
```

### Square Shape

<div style={{padding:"24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb",display:"flex",gap:"16px",alignItems:"center"}}>
  <div style={{width:"36px",height:"36px",borderRadius:"8px",background:"#0479CE",display:"flex",alignItems:"center",justifyContent:"center"}}>
    <span style={{color:"#fff",fontSize:"12px",fontWeight:600,fontFamily:"Inter,sans-serif"}}>AD</span>
  </div>

  <div style={{width:"48px",height:"48px",borderRadius:"10px",background:"#16A34A",display:"flex",alignItems:"center",justifyContent:"center"}}>
    <span style={{color:"#fff",fontSize:"14px",fontWeight:600,fontFamily:"Inter,sans-serif"}}>LG</span>
  </div>
</div>

```tsx theme={null}
<Avatar fallback="AD" shape="square" size="md" />
<Avatar fallback="AD" shape="square" size="lg" />
```

### Avatar Group

<div style={{padding:"24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb"}}>
  <div style={{display:"flex",alignItems:"center"}}>
    {["A1","A2","A3","A4"].map((init, i) => (
            <div key={init} style={{width:"32px",height:"32px",borderRadius:"50%",border:"2px solid #fff",background:`hsl(${i*40+200},70%,55%)`,display:"flex",alignItems:"center",justifyContent:"center",marginLeft:i>0?"-8px":"0",zIndex:4-i}}>
              <span style={{color:"#fff",fontSize:"10px",fontWeight:600,fontFamily:"Inter,sans-serif"}}>{init}</span>
            </div>
          ))}

    <div style={{width:"32px",height:"32px",borderRadius:"50%",border:"2px solid #fff",background:"#E4E4E7",display:"flex",alignItems:"center",justifyContent:"center",marginLeft:"-8px"}}>
      <span style={{color:"#52525B",fontSize:"10px",fontWeight:600,fontFamily:"Inter,sans-serif"}}>+2</span>
    </div>
  </div>
</div>

```tsx theme={null}
<AvatarGroup max={4} size="sm">
  <Avatar src="/user1.jpg" fallback="A1" />
  <Avatar src="/user2.jpg" fallback="A2" />
  <Avatar src="/user3.jpg" fallback="A3" />
  <Avatar src="/user4.jpg" fallback="A4" />
  <Avatar src="/user5.jpg" fallback="A5" />
  <Avatar src="/user6.jpg" fallback="A6" />
  {/* +2 overflow shown automatically */}
</AvatarGroup>
```

***

## API Reference

### Avatar

<ParamField path="src" type="string">
  Image URL. Falls back to `fallback` initials if the image fails to load.
</ParamField>

<ParamField path="alt" type="string">
  Alt text for the image element.
</ParamField>

<ParamField path="fallback" type="string">
  Initials shown when the image is unavailable (e.g. `"AD"`).
</ParamField>

<ParamField path="size" type="string" default="md">
  Avatar size. Values: `xs` · `sm` · `md` · `lg` · `xl`
</ParamField>

<ParamField path="shape" type="string" default="circle">
  Border radius variant. Values: `circle` · `square`
</ParamField>

<ParamField path="status" type="string">
  Status indicator dot color. Values: `online` · `away` · `busy` · `offline`
</ParamField>

<ParamField path="ring" type="boolean" default="false">
  Shows a ring border around the avatar.
</ParamField>

<ParamField path="className" type="string">
  Additional Tailwind classes for custom overrides.
</ParamField>

### AvatarGroup

<ParamField path="max" type="number">
  Maximum avatars to show before displaying an overflow count.
</ParamField>

<ParamField path="size" type="string" default="md">
  Applies uniformly to all avatars in the group.
</ParamField>

***

## Accessibility

* Avatar image uses an `<img>` element with `alt` text
* When no image is provided, `role="img"` and `aria-label` are set with the fallback value
* Status indicators have `aria-label` describing the status (e.g. "Online")
* `AvatarGroup` overflow count uses `aria-label` like "+2 more users"

***

## Do's & Don'ts

<CardGroup cols={2}>
  <Card title="Do" icon="check" iconType="solid" color="#16A34A">
    * Always provide `alt` text for avatars with images
    * Use `fallback` initials as a graceful degradation
    * Use `AvatarGroup` with `max` to cap the visible stack
    * Match avatar size to the surrounding content density
  </Card>

  <Card title="Don't" icon="xmark" iconType="solid" color="#DC2626">
    * Don't use avatars as clickable buttons without additional affordance
    * Don't show status indicators unless the status is live and meaningful
    * Don't use more than 5 stacked avatars without overflow count
    * Don't crop logos or brand icons in circular avatars — use square shape
  </Card>
</CardGroup>