# Avatar Component

Avatars represent users or entities by displaying images, icons, or characters.

## Usage {#usage}

Import the component:

```js
import 'mdui/components/avatar.js';
```

Import the TypeScript type:

```ts
import type { Avatar } from 'mdui/components/avatar.js';
```

Example:

```html
<mdui-avatar src="https://avatars.githubusercontent.com/u/3030330?s=40&v=4"></mdui-avatar>
```

## Examples {#examples}

### Image Avatar {#example-src}

Use the `src` attribute to set an image as the avatar, or pass an `<img>` element into the default slot.

```html
<mdui-avatar src="https://avatars.githubusercontent.com/u/3030330?s=40&v=4"></mdui-avatar>

<mdui-avatar>
  <img src="https://avatars.githubusercontent.com/u/3030330?s=40&v=4" alt="Example of profile picture"/>
</mdui-avatar>
```

The `fit` attribute controls how the image fits in its container. It works similarly to the native [`object-fit`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) property.

### Icon Avatar {#example-icon}

Use the `icon` attribute to set a Material Icon for the avatar. Alternatively, pass an icon element into the default slot.

```html
<mdui-avatar icon="people_alt"></mdui-avatar>

<mdui-avatar>
  <mdui-icon name="people_alt"></mdui-icon>
</mdui-avatar>
```

### Character Avatar {#example-char}

You can use any text in the default slot as the avatar.

```html
<mdui-avatar>A</mdui-avatar>
```

## mdui-avatar API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>src</td>
    <td>src</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>URL of the avatar image.</p>
</td>
  </tr>
  <tr>
    <td>fit</td>
    <td>fit</td>
    <td>true</td>
    <td>&#39;contain&#39; | &#39;cover&#39; | &#39;fill&#39; | &#39;none&#39; | &#39;scale-down&#39;</td>
    <td></td>
    <td><p>Image resizing method, similar to the CSS <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit" target="_blank" rel="noopener nofollow"><code>object-fit</code></a> property. Possible values:</p>
<ul>
<li><code>contain</code>: Scales the image to fit within the box while preserving aspect ratio. The image will be &quot;letterboxed&quot; if the aspect ratios do not match.</li>
<li><code>cover</code>: Scales the image to fill the box while preserving aspect ratio. The image will be clipped if the aspect ratios do not match.</li>
<li><code>fill</code>: Default. Scales the image to fill the box; the image may be stretched if aspect ratios do not match.</li>
<li><code>none</code>: No resizing.</li>
<li><code>scale-down</code>: Scales the image down to fit. Behaves like <code>none</code> or <code>contain</code>, whichever results in the smaller image.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>The Material Icons name for the avatar.</p>
</td>
  </tr>
  <tr>
    <td>label</td>
    <td>label</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Text description of the avatar.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Custom avatar content, such as letters, <code>&lt;img&gt;</code> elements, icons, etc.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>image</td>
    <td><p>Internal <code>&lt;img&gt;</code> element when using an image avatar.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Internal <code>&lt;mdui-icon&gt;</code> element when using an icon avatar.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Custom Properties

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner</td>
    <td><p>The corner radius of the component. You can use a specific pixel value, but it is recommended to reference <a href="/en/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
</tbody>
</table>