sp-avatar

NPM 1.6.0

View Storybook

Try it on Stackblitz
Overview API Changelog

Description

An <sp-avatar> is a great way to feature a visual representation of a user.

Usage

See it on NPM! How big is this package in your project? Try it on Stackblitz

yarn add @spectrum-web-components/avatar

Import the side effectful registration of <sp-avatar> via:

import '@spectrum-web-components/avatar/sp-avatar.js';

When looking to leverage the Avatar base class as a type and/or for extension purposes, do so via:

import { Avatar } from '@spectrum-web-components/avatar';

Sizes

50 
<sp-avatar
    size="50"
    label="Demo User"
    src="https://picsum.photos/500/500"
></sp-avatar>
 75 
<sp-avatar
    size="75"
    label="Demo User"
    src="https://picsum.photos/500/500"
></sp-avatar>
 100 
<sp-avatar
    size="100"
    label="Demo User"
    src="https://picsum.photos/500/500"
></sp-avatar>
 200 
<sp-avatar
    size="200"
    label="Demo User"
    src="https://picsum.photos/500/500"
></sp-avatar>
 300 
<sp-avatar
    size="300"
    label="Demo User"
    src="https://picsum.photos/500/500"
></sp-avatar>
 400 
<sp-avatar
    size="400"
    label="Demo User"
    src="https://picsum.photos/500/500"
></sp-avatar>
 500 
<sp-avatar
    size="500"
    label="Demo User"
    src="https://picsum.photos/500/500"
></sp-avatar>
 600 
<sp-avatar
    size="600"
    label="Demo User"
    src="https://picsum.photos/500/500"
></sp-avatar>
 700 
<sp-avatar
    size="700"
    label="Demo User"
    src="https://picsum.photos/500/500"
></sp-avatar>

Accessibility

The Avatar component is designed to be accessible by default. To ensure proper accessibility:

  1. Provide a label attribute when the avatar represents a user or has meaningful content:
<sp-avatar
    label="Shantanu Narayen"
    src="https://picsum.photos/500/500"
></sp-avatar>
  1. Use the isdecorative attribute when the avatar is purely decorative and should be hidden from screen readers:
<sp-avatar isdecorative src="https://picsum.photos/500/500"></sp-avatar>
  1. If neither label nor isdecorative is provided, a warning will be logged to the console to help developers identify accessibility issues.

Accessibility Features

  • When a label is provided, it is used as the alt text for the image
  • When isdecorative is true, the avatar is hidden from screen readers using aria-hidden="true"
  • The component maintains focus management for keyboard navigation
  • Color contrast meets WCAG 2.1 Level AA requirements

Accessibility Best Practices

  • Always provide a label for avatars that represent users or have meaningful content
  • Use isdecorative for purely decorative avatars
  • Avoid using avatars without either a label or isdecorative attribute
  • Ensure the avatar image has sufficient contrast with its background
  • When using avatars in interactive contexts (e.g., as buttons), ensure they have appropriate ARIA roles and labels

Best Practices

  • Always provide a meaningful label

Attributes and Properties

Property Attribute Type Default Description disabled disabled boolean false Disable this control. It will not receive focus or events download download string | undefined Causes the browser to treat the linked URL as a download. href href string | undefined The URL that the hyperlink points to. isdecorative isdecorative boolean false Whether this avatar is decorative and should be hidden from screen readers. When true, aria-hidden will be set to true and alt will be empty. When false and no label is provided, a warning will be logged. label label string | undefined An accessible label that describes the component. It will be applied to aria-label, but not visually rendered. referrerpolicy referrerpolicy | 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url' | undefined How much of the referrer to send when following the link. rel rel string | undefined The relationship of the linked URL as space-separated link types. size size AvatarSize src src string '' tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property target target '_blank' | '_parent' | '_self' | '_top' | undefined Where to display the linked URL, as the name for a browsing context (a tab, window, or <iframe>).

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/shared@1.6.0

1.5.0

Patch Changes

  • #5271 165a904 Thanks @renovate! - Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.

  • Updated dependencies []:

    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/shared@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Note: Version bump only for package @spectrum-web-components/avatar

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/avatar

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/avatar

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/avatar

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/avatar

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/avatar

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/avatar

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/avatar

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/avatar

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/avatar

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/avatar

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/avatar

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/avatar

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/avatar

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/avatar

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/avatar

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/avatar

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/avatar

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/avatar

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/avatar

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/avatar

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/avatar

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/avatar

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/avatar

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/avatar

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/avatar

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/avatar

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/avatar

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/avatar

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/avatar

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/avatar

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/avatar

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/avatar

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/avatar

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/avatar

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/avatar

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/avatar

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/avatar

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/avatar

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/avatar

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/avatar

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/avatar

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/avatar

0.30.0 (2023-05-03)

Bug Fixes

  • avatar: ensure there is ALWAYS a focusElement (c1c8644)
  • correct @element jsDoc listing across library (c97a632)
  • ensure browser understandable extensions (f4e59f7)
  • include "type" in package.json, generate custom-elements.json (1a8d716)
  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • use latest @spectrum-css/* versions (c35eb86)
  • use the "browsers" listing in postcss-preset-env (4eaf6a2)

Features

  • add screenshot regression testing to CI (8205dfe)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • avatar: add avatar component (a6882b4)
  • avatar: update spectrum css input (0a6f35a)
  • avatar: use core tokens (6937e68)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • update lit-* dependencies, wip (377f3c8)
  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

Reverts

  • Revert "chore: release new versions" (a6d655d)

0.11.4 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/avatar

0.11.3 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/avatar

0.11.2 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/avatar

0.11.1 (2023-02-21)

Bug Fixes

  • avatar: ensure there is ALWAYS a focusElement (c1c8644)

0.11.0 (2023-02-08)

Features

  • avatar: use core tokens (6937e68)

0.10.5 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/avatar

0.10.4 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/avatar

0.10.3 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/avatar

0.10.2 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/avatar

0.10.1 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/avatar

0.10.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.9.12 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.11 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.10 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.9 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.8 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.7 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.6 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.5 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.4 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.3 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.2 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.1 (2021-12-13)

Note: Version bump only for package @spectrum-web-components/avatar

0.9.0 (2021-11-08)

Features

  • update lit-* dependencies, wip (377f3c8)

0.8.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/avatar

0.8.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.7.9 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/avatar

0.7.8 (2021-08-24)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)

0.7.7 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/avatar

0.7.6 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/avatar

0.7.5 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/avatar

0.7.4 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/avatar

0.7.3 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/avatar

0.7.2 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/avatar

0.7.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/avatar

0.7.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.6.1 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.6.0 (2021-01-21)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)
  • use the "browsers" listing in postcss-preset-env (4eaf6a2)

Features

  • avatar: update spectrum css input (0a6f35a)

0.5.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • avatar: update spectrum css input (0a6f35a)

0.4.3 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/avatar

0.4.2 (2020-10-12)

Bug Fixes

  • include default export in the "exports" fields (f32407d)

0.4.1 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.4.0 (2020-08-31)

Features

  • update to Spectrum CSS v3.0.0 (e8b3d8f)

0.3.2 (2020-08-19)

Note: Version bump only for package @spectrum-web-components/avatar

0.3.1 (2020-07-24)

Bug Fixes

  • ensure browser understandable extensions (f4e59f7)

0.3.0 (2020-07-17)

Features

  • leverage "exports" field in package.json (321abd7)

0.2.6 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/avatar

0.2.5 (2020-04-16)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.2.4 (2020-04-07)

Note: Version bump only for package @spectrum-web-components/avatar

0.2.3 (2020-03-11)

Note: Version bump only for package @spectrum-web-components/avatar

0.2.2 (2020-01-06)

Note: Version bump only for package @spectrum-web-components/avatar

0.2.1 (2019-11-27)

Bug Fixes

  • include "type" in package.json, generate custom-elements.json (1a8d716)

0.2.0 (2019-11-19)

Features

  • add screenshot regression testing to CI (8205dfe)

0.1.0 (2019-10-18)

Features

  • avatar: add avatar component (a6882b4)