# dds-avatar



<!-- Auto Generated Below -->


## Overview

A person's avatar: their image, falling back to their initials, falling back to a generic placeholder. It is decorative and hidden from assistive technology unless the consumer sets `aria-label`, which turns it into an image with that name; `name` never becomes the accessible name.

## Usage

### Avatar

#### Initials and placeholder

Set `name` and the avatar draws the person's initials: one letter at `xs`, `s` and `m`, two at `l`, `xl` and `2xl`. With no `name` and no image it draws a generic placeholder.

```html
<dds-avatar name="Alex Johnson"></dds-avatar>
```

#### Images

Set `src` to show an image. If it fails to load, `fallback-src` is tried next, then the initials, then the placeholder.

```html
<dds-avatar
  name="Alex Johnson"
  src="/images/alex.jpg"
  fallback-src="/images/default.jpg"
></dds-avatar>
```

#### Accessible name

The avatar is decorative by default and hidden from assistive technology. `name` is never used as its accessible name. Set `aria-label` on the element to expose it as an image with that name.

```html
<dds-avatar
  name="Alex Johnson"
  src="/images/alex.jpg"
  aria-label="Alex Johnson"
></dds-avatar>
```

Use `show-name` to print the name beside the avatar. The visible text is then readable on its own, so `aria-label` is usually unnecessary.

```html
<dds-avatar name="Alex Johnson" show-name></dds-avatar>
```

#### Size and shape

`size` takes `xs`, `s`, `m`, `l`, `xl` or `2xl`, and `shape` takes `circle` or `square`.

```html
<dds-avatar name="Alex Johnson" size="xl" shape="square"></dds-avatar>
```

#### Tooltips

The avatar has no tooltip of its own. Wrap it in a tooltip component where one is needed.



## Properties

| Property      | Attribute      | Description                                                                 | Type                                         | Default     |
| ------------- | -------------- | --------------------------------------------------------------------------- | -------------------------------------------- | ----------- |
| `fallbackSrc` | `fallback-src` | The URL of the image to show instead if `src` fails to load.                | `string \| undefined`                        | `undefined` |
| `name`        | `name`         | The person's name, which the initials and the visible label are drawn from. | `string \| undefined`                        | `undefined` |
| `shape`       | `shape`        | Whether the avatar is a circle or a rounded square.                         | `"circle" \| "square"`                       | `"circle"`  |
| `showName`    | `show-name`    | Whether to show `name` as a visible label beside the avatar.                | `boolean`                                    | `false`     |
| `size`        | `size`         | Which step of the size scale to render at.                                  | `"2xl" \| "l" \| "m" \| "s" \| "xl" \| "xs"` | `"m"`       |
| `src`         | `src`          | The URL of the image to show.                                               | `string \| undefined`                        | `undefined` |


## Shadow Parts

| Part     | Description                                                            |
| -------- | ---------------------------------------------------------------------- |
| `"root"` | The outermost element, holding the avatar and its optional name label. |


## Dependencies

### Depends on

- [dds-icon](../icon)

### Graph
```mermaid
graph TD;
  dds-avatar --> dds-icon
  style dds-avatar fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*