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.
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.
Preview
Section titled “Preview”<nana-avatar
name="Kamau Juma"
src="https://images.pexels.com/photos/6569952/pexels-photo-6569952.jpeg?auto=compress&cs=tinysrgb&w=128&h=128&fit=crop"
size="lg"
></nana-avatar>
<nana-avatar name="Wanjiru Otieno" size="lg"></nana-avatar>
<nana-avatar name="Achieng Odhiambo" size="lg"></nana-avatar>
<nana-avatar name="Mwangi Kariuki" size="lg"></nana-avatar>
<nana-avatar name="Greenfield Estates" shape="square" size="lg"></nana-avatar> <script lang="ts">
import { NanaAvatar } from '$lib/components/ui/avatar';
</script>
<div class="flex flex-wrap items-center gap-3">
<NanaAvatar name="Amina Otieno" size="xs" />
<NanaAvatar name="Brian Mwangi" size="sm" />
<NanaAvatar name="Chloe Wanjiru" />
<NanaAvatar name="David Kiprop" size="lg" shape="square" />
<NanaAvatar name="Esther Achieng" size="xl" tone="primary" />
<NanaAvatar size="lg" />
</div> <nana-avatar name="Njeri Wambui" size="xs"></nana-avatar>
<nana-avatar name="Njeri Wambui" size="sm"></nana-avatar>
<nana-avatar name="Njeri Wambui" size="md"></nana-avatar>
<nana-avatar name="Njeri Wambui" size="lg"></nana-avatar>
<nana-avatar name="Njeri Wambui" size="xl"></nana-avatar> Fallbacks
Section titled “Fallbacks”A photograph that fails to load falls back to initials. With no name the avatar is decorative and shows whatever is in its slot.
<nana-avatar
name="Otieno Ouma"
src="https://example.invalid/missing.jpg"
></nana-avatar>
<nana-avatar><nana-icon name="user"></nana-icon></nana-avatar> Installation
Section titled “Installation”npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add avatar --framework web-componentsnpx @nana-tec/ui add avatar --framework svelteLands 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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
name | name | string | '' | Whose avatar it is: the accessible name, the initials and the colour |
shape | shape | AvatarShape | 'circle' | A circle, or a rounded square for organisations and things |
size | size | AvatarSize | 'md' | How large it is |
src | src | string | '' | The photograph |
tone | tone | AvatarTone | undefined | — | The colour behind the initials; picked from the name when unset |
Slots
| Slot | Description |
|---|---|
(default) | Shown when there is neither a photograph nor a name, such as a person icon |
CSS parts
| Part | Description |
|---|---|
::part(base) | The circle or square |
::part(image) | The photograph |
::part(initials) | The initials |
CSS custom properties
| Property | Description |
|---|---|
--nana-avatar-size | Width and height, overriding size |
NanaAvatar
| Prop | Type | Default |
|---|---|---|
src | string | '' |
name | string | '' |
size | AvatarSize | 'md' |
shape | AvatarShape | 'circle' |
tone | AvatarTone |
Also accepts Omit<HTMLAttributes<HTMLSpanElement>, 'class'>.