# @maggioli-design-system/mds-avatar

> mds-avatar is a web-component from Magma Design System, built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.

Latest version **4.5.4** (published 2026-02-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @maggioli-design-system/mds-avatar
pnpm add @maggioli-design-system/mds-avatar
yarn add @maggioli-design-system/mds-avatar
bun add @maggioli-design-system/mds-avatar
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.5.4 |
| Published | 2026-02-19 |
| First published | 2021-11-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 6 |
| Unpacked size | 1.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Vittorio Vittori |
| Maintainers | vitto, moodysmiles, nicola.tamburini.maggioli |

## Links

- npm: https://www.npmjs.com/package/@maggioli-design-system/mds-avatar
- npm.io page: https://npm.io/package/@maggioli-design-system/mds-avatar

## Dependencies (6)

- [clsx](https://npm.io/package/clsx.md) 2.1.0
- [fitty](https://npm.io/package/fitty.md) 2.4.2
- [@stencil/core](https://npm.io/package/@stencil/core.md) 4.27.2
- [@maggioli-design-system/styles](https://npm.io/package/@maggioli-design-system/styles.md) 15.11.0
- [@maggioli-design-system/mds-img](https://npm.io/package/@maggioli-design-system/mds-img.md) 4.3.7
- [@maggioli-design-system/mds-icon](https://npm.io/package/@maggioli-design-system/mds-icon.md) 2.13.3

## Recent versions

- 4.5.4 (latest) — 2026-02-19
- 4.5.3 — 2026-01-16
- 4.5.2 — 2025-06-03
- 4.5.1 — 2025-05-14
- 4.5.0 — 2025-04-18
- 4.4.0 — 2025-04-02
- 4.3.1 — 2025-03-10
- 4.3.0 — 2025-03-05
- 4.2.0 — 2025-02-25
- 4.1.1 — 2025-02-06
- 4.1.0 — 2024-12-05
- 4.0.0 — 2024-11-25
- 3.11.6 — 2024-10-17
- 3.11.5 — 2024-10-16
- 3.11.4 — 2024-10-14
- … 39 more at https://npm.io/package/@maggioli-design-system/mds-avatar/versions

## README

# mds-avatar

<!-- Start script-generated Magma Docs -->

# Install

Install the component via `npm` by running the following command

```bash
npm install @maggioli-design-system/mds-avatar
```

This package works also with yarn:

```bash
yarn add @maggioli-design-system/mds-avatar
```

### Import

Import the component in your project via `TypeScript` as follows:

```typescript
import { defineCustomElements as dceMdsAvatar } from '@maggioli-design-system/mds-avatar/loader'

dceMdsAvatar()
```

If you need to support older browsers (i.e. IE or early version of Edge), you can wrap the `defineCustomElements` in another utility awailable in the same package:

```typescript
import { applyPolyfills as apMdsAvatar, defineCustomElements as dceMdsAvatar } from '@maggioli-design-system/mds-avatar/loader'

apMdsAvatar().then(dceMdsAvatar())
```

Use alias for `defineCustomElements` method to initialize multiple web components in the same place:

```typescript
import { defineCustomElements as dceMdsComponentOne } from '@maggioli-design-system/mds-component-one/loader'
import { defineCustomElements as dceMdsComponentTwo } from '@maggioli-design-system/mds-component-two/loader'

dceMdsComponentOne()
dceMdsComponentTwo()
```

You can check how browser support works at [this page][stencil-browser-support].

# Integration

<!-- This section is useful to describe usages and configurations -->

#### How to use it in HTML

<!-- Add information about HTML usage here -->

`MdsAvatar` accepts a path to an image to be displayed via the `src` attribute, or if missing accepts the initials to be displayed via the `initials` attribute. Beware that the text passed via `initials` attribute will be trimmed and truncated up to the second character, so if `cya` is the value passed to the attribute, the final result displayed will be `CY` (the text will be transformed to uppercase via a css class).

An example follows:

```html
<mds-avatar src="https://placehold.co/80" initials="ap"></mds-avatar>
```

You can try it out on the component's [Storybook website][storybook]!

<!-- TODO set correct storybook link, `ui` may need to be changed into something else -->
[storybook]: https://magma.maggiolicloud.it/storybook/?path=/story/ui-avatar--default
[stencil-browser-support]: https://stenciljs.com/docs/browser-support

<!-- End script-generated Magma Docs -->

---

This is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.

<!-- Auto Generated Below -->


## Properties

| Property   | Attribute  | Description                                                                                                                                          | Type                                                                                                                                                                                    | Default     |
| ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `count`    | `count`    | The user's inizials displayed if there's no image available, initials will override tone and variant senttings to keep user recognizable from others | `number \| undefined`                                                                                                                                                                   | `undefined` |
| `icon`     | `icon`     | Specifies the path to the icon                                                                                                                       | `string \| undefined`                                                                                                                                                                   | `undefined` |
| `initials` | `initials` | The user's inizials displayed if there's no image available, initials will override tone and variant senttings to keep user recognizable from others | `string \| undefined`                                                                                                                                                                   | `undefined` |
| `src`      | `src`      | Specifies the path to the image                                                                                                                      | `string \| undefined`                                                                                                                                                                   | `undefined` |
| `tone`     | `tone`     | Specifies the color tone of the component                                                                                                            | `"strong" \| "weak" \| undefined`                                                                                                                                                       | `undefined` |
| `variant`  | `variant`  | Specifies the color variant of the component                                                                                                         | `"amaranth" \| "aqua" \| "blue" \| "error" \| "green" \| "info" \| "lime" \| "orange" \| "orchid" \| "primary" \| "sky" \| "success" \| "violet" \| "warning" \| "yellow" \| undefined` | `undefined` |


## Shadow Parts

| Part        | Description                                |
| ----------- | ------------------------------------------ |
| `"icon"`    | The selected icon of the avatar            |
| `"wrapper"` | The wrapper which contains media displayed |


## CSS Custom Properties

| Name                                    | Description                                   |
| --------------------------------------- | --------------------------------------------- |
| `--mds-avatar-background-color`         | The background-color of the component         |
| `--mds-avatar-background-color-pending` | The background-color when an image is loading |
| `--mds-avatar-color`                    | The color of the placeholder icon             |
| `--mds-avatar-radius`                   | The border-radius of the element              |


## Dependencies

### Used by

 - [mds-avatar-stack-item](../mds-avatar-stack-item)
 - [mds-entity](../mds-entity)
 - [mds-push-notification-item](../mds-push-notification-item)

### Depends on

- [mds-img](../mds-img)
- [mds-icon](../mds-icon)

### Graph
```mermaid
graph TD;
  mds-avatar --> mds-img
  mds-avatar --> mds-icon
  mds-img --> mds-icon
  mds-img --> mds-text
  mds-img --> mds-button
  mds-button --> mds-spinner
  mds-button --> mds-icon
  mds-button --> mds-text
  mds-avatar-stack-item --> mds-avatar
  mds-entity --> mds-avatar
  mds-push-notification-item --> mds-avatar
  style mds-avatar fill:#f9f,stroke:#333,stroke-width:4px
```

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

Built with love @ [Gruppo Maggioli](https://www.maggioli.com) from [R&D Department](https://www.maggioli.com/it-it/chi-siamo/ricerca-sviluppo)

---
_Source: https://npm.io/package/@maggioli-design-system/mds-avatar · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
