Avatar

<pc-avatar>

0.1.0

experimental

Avatars are used to represent a person or object.

By default, a generic icon will be shown. You can personalise avatars by adding custom icons, initials and images. You should always provide a label for assistive devices.

<pc-avatar label="User avatar"></pc-avatar>

Code

Edit

Demos

Images

To use an image for the avatar, set the image and label attributes. This will take priority and be shown over initials and icons. Avatar images can be lazy‐loaded by setting the loading attribute to lazy.

<pc-avatar image="/favicon.svg" label="Placer Toolkit’s avatar"></pc-avatar>

Code

Edit

Initials

When you don’t have an image to use, you can set the initials attribute to show something more personalised than an icon.

<pc-avatar initials="PC" label="Avatar with initials: PC"></pc-avatar>

Code

Edit

Custom icons

When no image or initials are set, an icon will be shown. The default avatar shows the Font Awesome user icon, but you can customise this with the icon slot.

<pc-avatar label="Avatar with an image icon">
    <pc-icon
        library="default"
        icon-style="solid"
        name="image"
        slot="icon"
    ></pc-icon>
</pc-avatar>

<pc-avatar label="Avatar with an ZIP file icon">
    <pc-icon
        library="default"
        icon-style="solid"
        name="file-zipper"
        slot="icon"
    ></pc-icon>
</pc-avatar>

<pc-avatar label="Avatar with a suitcase icon">
    <pc-icon
        library="default"
        icon-style="solid"
        name="suitcase"
        slot="icon"
    ></pc-icon>
</pc-avatar>

Code

Edit

Shapes

Avatar shapes can be changed with the shape attribute.

<pc-avatar shape="square" label="Square avatar"></pc-avatar>
<pc-avatar shape="rounded" label="Rounded avatar"></pc-avatar>
<pc-avatar shape="circle" label="Circular avatar"></pc-avatar>

Code

Edit

Avatar groups

You can group avatars into an avatar group with a few lines of CSS.

<div class="avatar-group">
    <pc-avatar
        image="https://placer-toolkit.vercel.app/brand/logo-in-circle.svg"
        label="Placer Toolkit’s avatar (original, 1 of 4)"
    ></pc-avatar>
    <pc-avatar
        image="https://placer-toolkit.vercel.app/brand/logo-in-circle.svg"
        label="Placer Toolkit’s avatar (greyscale filter added, 2 of 4)"
    ></pc-avatar>
    <pc-avatar
        image="https://placer-toolkit.vercel.app/brand/logo-in-circle.svg"
        label="Placer Toolkit’s avatar (hue rotated by 180º, 3 of 4)"
    ></pc-avatar>
    <pc-avatar
        image="https://placer-toolkit.vercel.app/brand/logo-in-circle.svg"
        label="Placer Toolkit’s avatar (sepia filter added, 4 of 4)"
    ></pc-avatar>
</div>

<style>
    .avatar-group pc-avatar:not(:first-of-type) {
        margin-inline-start: -1em;
    }

    .avatar-group pc-avatar:nth-child(2) {
        filter: grayscale(100%);
    }

    .avatar-group pc-avatar:nth-child(3) {
        filter: hue-rotate(180deg);
    }

    .avatar-group pc-avatar:last-child {
        filter: sepia(100%);
    }

    .avatar-group pc-avatar::part(base) {
        border: var(--pc-border-width-m) var(--pc-border-style)
            var(--pc-color-surface-default);
    }
</style>

Code

Edit

Properties

Name	Description	Default
`image`	The image source to use for the avatar. Type: `string`	`""`
`label`	A label to use to describe the avatar to assistive devices. Type: `string`	`""`
`initials`	Initials to use as a fallback when no image is available (1–2 characters recommended). Type: `string`	`""`
`loading`	Indicates how the browser should load the image. Type: `"eager" \| "lazy"`	`"eager"`
`shape`	The shape of the avatar. Type: `"circle" \| "rounded" \| "square"`	`"circle"`
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	‐

Learn more about customising animations.

Slots

Name	Description
`icon`	The default icon to use when no image or initials are present. Works best with `<pc-icon>`.

Learn more about using slots.

Events

Name	Description	Event detail
`pc-error`	Emitted when the image couldn’t be loaded. This may be because of an invalid URL, a temporary network error or some other unknown cause.	‐

Learn more about events.

Custom properties

Name	Description	Default
`--size`	The size of the avatar.	`3rem`

Learn more about customising custom properties.

Parts

Name	Description
`base`	The component’s base wrapper.
`icon`	The container that wraps the avatar’s icon.
`initials`	The container that wraps the avatar’s initials.
`image`	The avatar image. Only shown when the `image` attribute is set.

Learn more about customising CSS parts.

Importing

If you’re using the autoloader or the standard loader, you can skip this section. But if you’re cherry picking, you can use any of the following snippets to import this component.

CDN (script tag)

CDN (import)

npm (import)

To manually import this component from the CDN, copy this code snippet and paste it in your HTML.

  <script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/avatar/avatar.js"></script> 

To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.

  import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/avatar/avatar.js"; 

To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.

import "placer-toolkit/dist/components/avatar/avatar.js";

Dependencies

This component automatically imports these components:

Icon