Avatar

A small identity badge — a person’s picture, or their initials on a filled tile when there’s no image. It’s a circle by default, with rounded-square and square options. Avatar builds on the same image pipeline as Picture: the image is scaled to cover the badge and clipped to its shape.

Usage

From an image

Pass an Image handle, a file path, or a PIL image. It is scaled to cover the square and clipped to the shape:

bs.Avatar("alice.jpg", size=48)
bs.Avatar(Image.open("bob.png"), size=64, shape="rounded")

From initials

With no image, the avatar shows initials on a background tile. Give a name to derive them (first and last initial), or pass initials directly:

bs.Avatar(name="Ada Lovelace")            # -> "AL"
bs.Avatar(name="Grace Hopper", background="info")
bs.Avatar(initials="JD", background="success")

If an image is given but fails to load, the avatar falls back to initials (or a plain background tile) automatically.

Shape and size

size sets the square’s edge in pixels; shape is 'circle' (default), 'rounded', or 'square':

bs.Avatar(photo, size=72, shape="circle")
bs.Avatar(photo, size=72, shape="rounded")
bs.Avatar(photo, size=72, shape="square")

Colors and clicks

background colors the initials tile (and the fallback), foreground the initials text — both take a theme color token or a hex string. on_click makes the avatar an entry point (open a profile, a menu, …):

avatar = bs.Avatar(name="Ada Lovelace", background="primary", foreground="white")
avatar.on_click(lambda e: open_profile())

Swap the picture at runtime through the image property, or update the initials with set_initials.

See also

• Picture — the general image-display widget.

• Image — the image source handle.

API

The complete reference for Avatar lives on the Widgets API page. At a glance:

Avatar

A small identity badge — a picture or initials on a filled tile.

Full Example

# The sample photo lives alongside the docs' example media.
_PHOTO = Path(__file__).parent.parent / "_static" / "examples" / "avatar-profile.jpg"

with bs.App(title="Avatar", padding=20, gap=16) as app:
    bs.Label("From an image", font="heading-md")
    with bs.HStack(gap=12, anchor_items="center"):
        bs.Avatar(_PHOTO, size=64, shape="circle")
        bs.Avatar(_PHOTO, size=64, shape="rounded")
        bs.Avatar(_PHOTO, size=64, shape="square")
        bs.Avatar(_PHOTO, size=40)
        bs.Avatar(_PHOTO, size=28)

    bs.Separator()

    bs.Label("From initials", font="heading-md")
    with bs.HStack(gap=12, anchor_items="center"):
        bs.Avatar(name="Ada Lovelace", size=64, background="primary")
        bs.Avatar(name="Grace Hopper", size=64, background="info")
        bs.Avatar(name="Alan Turing", size=64, background="success")
        bs.Avatar(initials="JD", size=64, background="warning")
        bs.Avatar(name="Katherine Johnson", size=64, background="#7c4dff", shape="rounded")

    bs.Separator()

    bs.Label("Clickable (prints to the console)", font="heading-md")
    avatar = bs.Avatar(_PHOTO, size=56)
    avatar.on_click(lambda e: print("avatar clicked"))

app.run()