Skip to content
Nana UI

Data Display & Media

Avatar

A person, shown by their photograph or, when there is none or it fails to load, by their initials on a colour picked from their name — so the same tenant is the same colour on every screen. The colours avoid the status tones, so an avatar is never mistaken for a warning.

View .md Download

Give it a name and it is announced as that person; without one it is decoration and hidden from assistive tech. Put an icon in the slot to show something other than initials when there is no name.

A photograph that fails to load falls back to initials. With no name the avatar is decorative and shows whatever is in its slot.

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add avatar --framework web-components
npx @nana-tec/ui add avatar --framework svelte

Lands in src/lib/components/ui/avatar/ as NanaAvatar.svelte, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

import "@nana-tec/ui-components/avatar";

Copied in with npx @nana-tec/ui add avatar? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

<nana-avatar name="Kamau Juma" src="/avatars/kamau.jpg"></nana-avatar>
<nana-avatar name="Wanjiru Otieno" size="lg"></nana-avatar>
<script lang="ts">
import { NanaAvatar } from '$lib/components/ui/avatar';
</script>
<NanaAvatar name="Amina Otieno" src="/people/amina.jpg" />

Without a picture, or when the picture fails to load, it shows the person’s initials on a colour picked from their name, so the same person is always the same colour. With no name it shows a plain figure and is hidden from screen readers.

Properties

PropertyAttributeTypeDefaultDescription
namenamestring''Whose avatar it is: the accessible name, the initials and the colour
shapeshapeAvatarShape'circle'A circle, or a rounded square for organisations and things
sizesizeAvatarSize'md'How large it is
srcsrcstring''The photograph
tonetoneAvatarTone | undefined—The colour behind the initials; picked from the name when unset

Slots

SlotDescription
(default)Shown when there is neither a photograph nor a name, such as a person icon

CSS parts

PartDescription
::part(base)The circle or square
::part(image)The photograph
::part(initials)The initials

CSS custom properties

PropertyDescription
--nana-avatar-sizeWidth and height, overriding size

NanaAvatar

PropTypeDefault
srcstring''
namestring''
sizeAvatarSize'md'
shapeAvatarShape'circle'
toneAvatarTone

Also accepts Omit<HTMLAttributes<HTMLSpanElement>, 'class'>.