بَسْمَة — a smile. بَصْمَة — a fingerprint.

One word in Latin letters; two in Arabic. The difference is whether you read it with a sīn (س) or a ṣād (ص). An avatar is both at once: a face, and a mark no one else has.

Give it a value, get a stable avatar: two characters or one of 60 shapes, on a matched colour palette. The same value always produces the same avatar, and no network request is ever made.

Credit

Basma is a Vue port of avvvatars by Nusu Alabuga. The generation algorithm, the colour palettes, and every one of the 60 shapes are his original work — this port contributes only the Vue rendering layer. If Basma is useful to you, go star the original and visit avvvatars.com.

Licensed MIT; the upstream licence is retained in LICENSE.avvvatars.

Install

pnpm add @zamanapp/basma

Vue 3.3+ is a peer dependency.

Usage

<script setup>
import Basma from '@zamanapp/basma'
</script>

<template>
  <Basma value="[email protected]" />
  <Basma value="[email protected]" variant="shape" :size="64" />
</template>

Or register it globally:

import { BasmaPlugin } from '@zamanapp/basma'
app.use(BasmaPlugin)

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | value | string | required | The identity the avatar is derived from — a user id, email, or full name. | | displayValue | string | — | Characters to show instead of value. Does not change the colour or shape. | | size | number | 32 | Width and height in pixels. Text and shape scale with it. | | variant | 'character' \| 'shape' | 'character' | Show two characters, or a shape. | | theme | 'light' \| 'dark' \| 'system' | 'system' | Colour theme. dark swaps surface and mark; system follows prefers-color-scheme. | | shadow | boolean | false | Apply a subtle drop shadow. | | border | boolean | false | Draw a border. | | borderSize | number | 2 | Border width in pixels. Requires border. | | borderColor | string | '#fff' | Border colour. Requires border. | | radius | number | size | Corner radius in pixels. Defaults to a full circle. |

Because value seeds the avatar and displayValue does not, you can relabel a user without changing the avatar they are recognised by.

Dark mode

By default the avatar follows the OS colour scheme. In dark mode the palette is swapped rather than recomputed: the avatar's dark tone becomes the surface and its light tone becomes the initials or shape — same identity, legible on a dark background. generate() output never changes, so parity with avvvatars holds.

<Basma value="[email protected]" theme="dark" />

Headless use

The generator is exported separately if you want to render the avatar yourself:

import { generate } from '@zamanapp/basma'

generate('[email protected]')
// { initials, backgroundColor, textColor, shapeColor, shape: { d, evenOdd }, viewBox }

SHAPES, SHAPE_VIEWBOX, BACKGROUND_COLORS, TEXT_COLORS and SHAPE_COLORS are exported too.

Coming from avvvatars?

The same value gives you the same avatar you'd get from avvvatars, and every prop works the same way — with one rename to know about:

• Use variant="shape", not style="shape". Vue treats style as a special attribute, so it can't be used as a prop name here. Everything else is identical.

Basma also ships with zero runtime dependencies, and you can drop as many avatars on a page as you like without them clashing — a nice-to-have that the original couldn't offer.

License

MIT — see LICENSE.