Lism CSS
Docs
Search

Avatar

This page is currently under construction
Lism UI (@lism-css/ui) is still in preparation.

A component for displaying avatar images. When no image is available, it can show the first letter of a name as a placeholder.

Overview

↓
Preview
Avatar of xxxx
<Avatar size="4rem" src="https://cdn.lism-css.com/img/avatar/EkABPzB34XR7.webp" alt="Avatar of xxxx" />

Styles

The Avatar base styles are defined in the following CSS.

_style.css 
@layer lism-block {
  /* src ありの通常時: l--frame との併用が前提 */
  .b--avatar {
    --w: 2em; /* size prop未指定時のデフォルトサイズ */
    width: var(--w);
    aspect-ratio: 1/1;
    border-radius: var(--bdrs--99);
  }

  /* src 未指定時: name のイニシャル1文字を表示する。l--center との併用が前提 */
  .b--avatar--initial {
    --lh: 1;
    background-color: var(--base-2);
    text-transform: uppercase;
    user-select: none;

    /* --w が em単位の時を考慮し、子要素側で計算する */
    > * {
      font-size: calc(var(--w) / 2);
    }
  }
}

The full source code is available on GitHub.

Usage

Provided as Avatar (b--avatar) from the @lism-css/ui package.

Import

import { Avatar } from '@lism-css/ui/react';

Props

Prop Description
size Specifies the size of the avatar. Default: "2em"
src Path to the avatar image. When omitted, the initial of name is shown instead.
name User name. When src is omitted, its first character is shown as the initial. Also used as the alt text when alt is not specified.
alt Alt text. Takes precedence over name when specified. Use alt="" to treat the avatar as decorative, e.g. when the name is displayed right next to it.

Examples

↓
Avatar examples
Avatar of xxxx
Avatar of xxxx
<Avatar size="4rem" src="https://cdn.lism-css.com/img/avatar/EkABPzB34XR7.webp" alt="Avatar of xxxx"/>
<Avatar size="5rem" src="https://cdn.lism-css.com/img/avatar/of5v8rPFMI8F.webp" alt="Avatar of xxxx" bd bdw="2px" bdc="base" bxsh="20"/>

Initial fallback

When src is omitted, the root switches from l--frame to l--center, gets b--avatar--initial, and renders the first character of name in the center. Uppercasing is handled by CSS (text-transform: uppercase), and the font size scales with the avatar size (--w).

The styles are applied to b--avatar--initial on the root element, so the background color can be overridden with props such as bgc.

↓
Showing an initial by omitting src
Y
鈴
<Avatar size="2rem" name="Yamada Taro" />
<Avatar size="3rem" name="鈴木" bgc="brand" c="base" />

There is no automatic switch to the initial when the image fails to load. Since the Astro version renders static HTML, client-side load-state tracking is intentionally not included.

Without @lism-css/ui

This example builds an Avatar with lism-css primitives only, without @lism-css/ui.

↓
Example
Avatar of xxxx
<Frame ar="1/1" w="4em" bdrs="99">
  <img src="https://cdn.lism-css.com/img/avatar/EkABPzB34XR7.webp" alt="Avatar of xxxx" width="100%" height="100%" decoding="async" />
</Frame>

© 2026 Lism CSS.