Avatar

A person or a thing, as a disc. A picture when there is one, an icon or the initials when there is not, on a colour derived from the name so the same person keeps the same one everywhere.

Usage

vue

<script setup lang="ts">
import { VAvatar } from 'vectis-ui'
</script>

<template>
  <VAvatar name="Ada Lovelace" />
</template>

Examples

With a picture

src displays a picture. name provides its alternative text and the initials shown when the file cannot be loaded.

vue

<script setup lang="ts">
import { VAvatar } from 'vectis-ui'

// NASA portrait of astronaut Anna Fisher, 1978. Public domain.
import portrait from '~/assets/img/anna-fisher.jpg'
</script>

<template>
  <VAvatar :src="portrait" name="Anna Fisher" size="lg" />
</template>

With an icon

icon displays an icon instead of the initials. alt names the avatar when no name is given.

vue

<script setup lang="ts">
import { VAvatar } from 'vectis-ui'
import { code, notifications, table_chart as tableChart } from 'vectis-ui/icons'
</script>

<template>
  <VAvatar :icon="code" alt="Build bot" />
  <VAvatar :icon="notifications" alt="System alerts" />
  <VAvatar :icon="tableChart" alt="Nightly report" />
</template>

Initials and automatic colour

With no picture and no icon, the disc shows the initials of name on a colour derived from it.

vue

<script setup lang="ts">
import { VAvatar } from 'vectis-ui'
</script>

<template>
  <VAvatar name="Ada Lovelace" />
  <VAvatar name="Grace Hopper" />
  <VAvatar name="Alan Turing" />
</template>

Sizes

size sets the diameter: 24, 32, 40, 48 or 56 pixels. The content inside follows.

vue

<script setup lang="ts">
import { VAvatar } from 'vectis-ui'
</script>

<template>
  <VAvatar name="Ada Lovelace" size="xs" />
  <VAvatar name="Ada Lovelace" size="sm" />
  <VAvatar name="Ada Lovelace" size="md" />
  <VAvatar name="Ada Lovelace" size="lg" />
  <VAvatar name="Ada Lovelace" size="xl" />
</template>

Compact

compact reduces the diameter by 4px.

vue

<script setup lang="ts">
import { VAvatar } from 'vectis-ui'
</script>

<template>
  <VAvatar name="Ada Lovelace" size="sm" />
  <VAvatar name="Ada Lovelace" size="sm" compact />
  <VAvatar name="Ada Lovelace" size="md" />
  <VAvatar name="Ada Lovelace" size="md" compact />
  <VAvatar name="Ada Lovelace" size="lg" />
  <VAvatar name="Ada Lovelace" size="lg" compact />
</template>

Custom colour

color replaces the colour derived from the name. Hex, a CSS colour name and oklch() are accepted.

vue

<script setup lang="ts">
import { VAvatar } from 'vectis-ui'
</script>

<template>
  <VAvatar name="Vectis UI" color="#6d28d9" />
  <VAvatar name="Atlas" color="teal" />
  <VAvatar name="Meridian" color="oklch(0.55 0.18 25)" />
</template>

Buttons and links

clickable renders a <button> and href an <a>, the address winning when both are given. disabled makes the avatar inert.

vue

Profile opened 0 times

<script setup lang="ts">
import { ref } from 'vue'
import { VAvatar, VTypography } from 'vectis-ui'

const opened = ref(0)
</script>

<template>
  <VAvatar name="Ada Lovelace" clickable @click="opened += 1" />
  <VAvatar name="Grace Hopper" href="#usage" />
  <VAvatar name="Alan Turing" href="#usage" disabled />
  <VTypography variant="body-sm" tone="muted">Profile opened {{ opened }} times</VTypography>
</template>

A VTooltip needs a focusable trigger: make the avatar clickable or a link, then bind the tooltip triggerProps onto it.

vue

<script setup lang="ts">
import { VAvatar, VTooltip } from 'vectis-ui'
</script>

<template>
  <VTooltip text="Ada Lovelace, on call until Friday">
    <template #default="{ triggerProps }">
      <VAvatar name="Ada Lovelace" clickable v-bind="triggerProps" />
    </template>
  </VTooltip>
</template>

API

Props

Prop	Type	Default
`src`	`string`	none
The picture to show. It is preferred above everything else, and an image that fails to load hands over to the icon or the initials rather than leaving a gap.
`icon`	`IconSource`	none
The icon to show when there is no picture. It comes before the initials, so an avatar given both an icon and a name shows the icon.
`name`	`string`	none
The full name. It does three things at once: it names the avatar for assistive technology, its initials are what shows when there is no picture and no icon, and it is the seed the automatic colour is derived from.
`alt`	`string`	none
The accessible name, when it should not simply be the name: an avatar standing for a team rather than a person, say. It wins over `name`, and an `aria-label` of yours wins over it. On a picture it is the image's `alt` text.
`color`	`string`	none
A colour of your own, as hex, a CSS name or `oklch()`. It replaces the hue otherwise derived from `name`, and the text on it is always white, so a light colour is yours to check.
`size`	`AvatarSize'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`
The diameter of the disc, from the size scale shared by every control. Left out inside a VAvatarGroup it takes the group's size; on its own it is `md`.
`compact`	`boolean`	`false`
Takes 4px off the diameter, as it does on every other control. Unlike the size it is cumulative: inside a compact VAvatarGroup the avatar is compact whatever this says.
`href`	`string`	none
Turns the avatar into an `<a>` pointing at this address. A disabled link becomes inert: the address is dropped, so it can be neither focused nor followed.
`clickable`	`boolean`	`false`
Turns the avatar into a `<button>`. It is ignored as soon as `href` makes it a link.
`disabled`	`boolean`	`false`
Makes an interactive avatar unusable: it stops responding, leaves the tab order and greys out. It says nothing on a plain avatar, which was never interactive.

Slots

Slot	Type
`default`	`{}`
Content replacing the initials.

Types

The types the tables above name, written as the library declares them. The ones carrying export can be imported from vectis-ui to type your own code; the others are the shape of what a slot hands out.

export interface BuiltinIcon {
  name: string
  paths: readonly [string] | readonly [string, string]
}

export type IconRender =
  | { path: string; viewBox?: string }
  | { component: Component; props?: Record<string, unknown> }
  | { src: string }
  | { text: string; class?: string }
  | { class: string }

export type IconSource = string | BuiltinIcon | IconRender

CSS variables

Token	Value
`--vectis-control-size-avatar-ring`	`2px`