# Avatar

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/avatar

The `.avatar` component is a visual representation of a user. It shows the user's initials or an image thumbnail.
Its default size is 56px. (See the [HTML](#html) section below for all options.)

<Avatar status="online" size="xl" imageSrc={imageSrc}>SR</Avatar>

<div class="docs_oversizedTable">

| File                   | Description | Source      |
| ---------------------- | ----------- | ----------- |
| `component.avatar.css` | All avatar styles (`.avatar`) | [Github][1] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.avatar.css

## Playground

<Playground
  client:visible
  template={`<div class="{classes}">
  <div>{content}</div>
</div>`}
  baseClasses="avatar"
  snippets={{
    initials: { preview: "<span>SR</span>", code: "<span>SR</span>" },
    image: {
      preview: `<img src="${imageSrc.src}" alt="Sonny Rollins">`,
      code: `<img src="sonny.png" alt="Sonny Rollins">`,
    },
  }}
  controls={[
    { heading: "Variation", items: [
      { type: "select", name: "size", label: "Size", default: "", options: [
        { label: "Default", value: "" },
        { label: "Small", value: "avatar-sm" },
        { label: "Medium", value: "avatar-md" },
        { label: "Large", value: "avatar-lg" },
        { label: "Extra large", value: "avatar-xl" },
      ]},
    ]},
    { heading: "State", items: [
      { type: "select", name: "status", label: "Status", default: "", options: [
        { label: "None", value: "" },
        { label: "Online", value: "is-online" },
        { label: "Offline", value: "is-offline" },
      ]},
    ]},
    { heading: "Content", items: [
      { type: "select", name: "content", label: "Show", snippet: "content", default: "initials", options: [
        { label: "Initials", value: "initials", class: "", snippet: "initials" },
        { label: "Image", value: "image", class: "", snippet: "image" },
      ]},
    ]},
  ]}
/>

## HTML

### Available modifiers

<div class="docs_oversizedTable">

| Available modifiers           | Description                |
| ----------------------------- | -------------------------- |
| `.avatar`                     | Default - 56px             |
| `.avatar` + `.avatar-sm`      | Small - 24px               |
| `.avatar` + `.avatar-md`      | Medium - 36px              |
| `.avatar` + `.avatar-lg`      | Large - 80px               |
| `.avatar` + `.avatar-xl`      | Extra large - 128px        |
| `.avatar` + `.is-online`  | User is online - green dot |
| `.avatar` + `.is-offline` | User is offline - grey dot |

</div>

### Custom properties

The following custom properties are available in [`settings.ui.css`](/docs/tokens#interface-tokens):

<div class="docs_oversizedTable">

| Property                            | Color                             |
| ----------------------------------- | --------------------------------- |
| `--avatar-color`                    | Text color (when no image).       |
| `--avatar-background-color`         | Background color (when no image). |
| `--avatar-border-color`             | Border color.                     |
| `--avatar-border-width`             | Border width.                     |
| `--avatar-radius`                   | Radius. (`0` = square).           |
| `--avatar-status-dot-color-offline` | Status dot color: offline.        |
| `--avatar-status-dot-color-online`  | Status dot color: online.         |

</div>

## Astro component

<div class="docs_oversizedTable prose">

| Prop         | Type      | Default   | Description                                                 |
| ------------ | --------- | --------- | ----------------------------------------------------------- |
| `size`       | `string`  | undefined | `sm`, `md`, `lg`, `xl` ([px values](#html))                 |
| `imageSrc`   | `string`  | undefined | Optional image.                                             |
| `status`     | `'online' \| 'offline'` | `undefined` | Shows a status dot (green online / grey offline)   |
| `class` | `string`  | undefined | Additional CSS classes, useful for [helper classes](/docs/helpers). |

</div>

## Examples

<ul class="docs_examples prose">
  <li>
    ### Full name vs initials

    <Avatar>Sonny Rollins</Avatar>
    <Avatar>SR</Avatar>

    ```astro
    ---
    import Avatar from "../../components/Avatar.astro";
    ---
    <Avatar>Sonny Rollins</Avatar>
    <Avatar>SR</Avatar>
    ```
    The astro component can take initials or a full name and will output initials if an image is not provided. It will output the full name in the `alt` attribute if an image is provided.

  </li>
  <li>
    ### Offline large avatar

    <Avatar status="offline" size="lg" imageSrc={imageSrc}>Sonny Rollins</Avatar>

    ```astro
    ---
    import Avatar from "../../components/Avatar.astro";
    import imageSrc from "../../assets/images/sonny.png";
    ---
    <Avatar status="offline" size="lg" imageSrc={imageSrc}>Sonny Rollins</Avatar>
    ```

  </li>
</ul>
### HTML examples

<ul class="docs_examples">
  <li>
    <Avatar>SR</Avatar>

    ```html
    <div class="avatar">
      <div>
        <span>SR</span>
      </div>
    </div>
    ```

  </li>
</ul>