# antuikit / Avatar

> Avatar with a ring, a readable colorless default, a `squircle` shape, a `variant` and `color` pair, and an `indicator` slot on the shape's corner.

Docs: https://antuikit.com/docs/components/avatar

## Install

npx antuikit@latest init
npx antuikit@latest add avatar

## Import

import { Avatar } from "@/components/ui/avatar";

## Demos

- [Basic](https://ui.antuikit.com/embed/avatar/basic.md): Give `Avatar` a `src`, an `icon` or text as `children`, and longer text like "User" scales down to fit the circle.
- [Variant](https://ui.antuikit.com/embed/avatar/variant.md): Set `variant` to `filled`, `solid` or `outlined` to choose how `color` is painted, with `filled` as the default once a color is set.
- [Colors](https://ui.antuikit.com/embed/avatar/colors.md): Set `color` to any color name, here every one the theme defines, and switch `variant` to compare the three treatments.
- [Shape](https://ui.antuikit.com/embed/avatar/shapes.md): Set `shape` to `square` or `squircle`, a smooth superellipse corner, instead of the default `circle`.
- [Size](https://ui.antuikit.com/embed/avatar/sizes.md): Set `size` to `small`, `medium` or `large`, or to a number of pixels for any other size.
- [Responsive size](https://ui.antuikit.com/embed/avatar/responsive-size.md): Pass `size` an object of breakpoints to change the avatar's size with the screen width, from `xs` up to `xxl`.
- [Auto font size](https://ui.antuikit.com/embed/avatar/auto-font-size.md): Text in `children` scales down to fit the circle, so one, two or three letters all stay inside it.
- [Gap](https://ui.antuikit.com/embed/avatar/gap.md): Set `gap` to change the space between the text and the edge of the circle, where a larger gap makes the text smaller.
- [Image avatars](https://ui.antuikit.com/embed/avatar/images.md): Pass `src`, and `srcSet` for sharper screens, to show a photo, with `alt` naming the person for screen readers.
- [Icon avatars](https://ui.antuikit.com/embed/avatar/icon-avatars.md): Pass `icon` any node, like an `Icon` from your pack, and color the avatar with `color` or a `bg-*` class.
- [Image fallback](https://ui.antuikit.com/embed/avatar/fallback.md): When `src` fails to load, the avatar shows its `children` or `icon` instead, so pass the initials or icon you would show anyway.
- [Skeleton](https://ui.antuikit.com/embed/avatar/loading.md): Show `Skeleton.Avatar` at the same `size` and `shape` while data loads, so the row does not move when the avatar arrives.
- [Status](https://ui.antuikit.com/embed/avatar/status.md): Show a state three ways at once: a colored ring, a corner icon through `indicator`, and a Tooltip that says it in words.
- [Grayscale](https://ui.antuikit.com/embed/avatar/grayscale.md): Add `grayscale` to `className` to desaturate an avatar until it is hovered, the usual way a directory marks someone as away.
- [Indicator](https://ui.antuikit.com/embed/avatar/indicator.md): Pass `indicator` a node, like a childless `Badge` or an icon, to place it on the avatar's corner, on the edge of any shape.
- [Indicator position](https://ui.antuikit.com/embed/avatar/indicator-position.md): Set `indicatorPosition` to a corner, or to `top-center` or `bottom-center` for the middle of an edge. `start` and `end` follow the text direction.
- [Badge](https://ui.antuikit.com/embed/avatar/with-badge.md): Put a childless `Badge` in `indicator` for a count, a dot, a capped count like 9+, an icon or a status dot.
- [Ring](https://ui.antuikit.com/embed/avatar/ring.md): Add a `ring-*` class with `ring-offset-container` to draw a ring outside the avatar, for a selected or error state.
- [Progress](https://ui.antuikit.com/embed/avatar/progress-ring.md): Wrap an avatar in a circle `Progress` sized from the avatar's pixel size, for a completion ring that can change color with the value.
- [Story ring](https://ui.antuikit.com/embed/avatar/story-ring.md): Wrap the avatar in a gradient ring and paint its border `border-container` to make the gap, for unseen, seen, live, broadcasting and dashed stories.
- [Removable](https://ui.antuikit.com/embed/avatar/removable.md): Overlay a `Button` on each avatar that shows on hover and on focus, with an `aria-label` naming the person it removes.
- [Group](https://ui.antuikit.com/embed/avatar/group.md): Wrap avatars in `Avatar.Group` to overlap them, and set `max.count` to fold the rest into a +2 chip that lists them on hover.
- [Group size and shape](https://ui.antuikit.com/embed/avatar/group-size.md): Set `size` and `shape` on the group to apply them to every avatar inside it.
- [Group overlap](https://ui.antuikit.com/embed/avatar/group-overlap.md): Set `overlap` to `none`, `medium` or `large` to change how far each face slides under the last, and add classes for a staggered or shadowed stack.
- [Group tooltips](https://ui.antuikit.com/embed/avatar/group-tooltips.md): Wrap each avatar in a `Tooltip` to show its name on hover, since a stacked group hides everyone's name.
- [Group in a pill](https://ui.antuikit.com/embed/avatar/group-pill.md): Set `surface` to put the group on a raised pill whose corners follow `shape` and whose avatar rings match it, with room for a label.
- [Expandable group](https://ui.antuikit.com/embed/avatar/group-hover.md): Set `expandOnHover` to spread the stack, or lift or color one face with classes. `Tooltip.UniqueProvider` slides one bubble between the faces.
- [Team stack](https://ui.antuikit.com/embed/avatar/team-stack.md): A project card with the team as an overlapping stack, a Tooltip naming each face, a +3 chip for the rest and an Invite button.
- [Account menu](https://ui.antuikit.com/embed/avatar/user-menu.md): An account menu in an app bar, opened from a `Button` with the `avatar` prop so the picture gets a keyboard-reachable trigger.
- [People picker](https://ui.antuikit.com/embed/avatar/people-picker.md): A people picker that keeps its dropdown open while you tick several names, and shows the chosen people as a stack below it.
- [Social proof](https://ui.antuikit.com/embed/avatar/social-proof.md): A marketing strip with a small stack of faces beside a join count, with `size` set once on the group.
- [Comment thread](https://ui.antuikit.com/embed/avatar/comment-thread.md): A discussion card where each comment has an avatar beside the author's name, a role tag and when it was posted.
- [Team directory](https://ui.antuikit.com/embed/avatar/presence-list.md): A team directory where each avatar carries a presence dot through `indicator`, matched by a status tag at the end of the row.
- [Story viewer](https://ui.antuikit.com/embed/avatar/story-viewer.md): A story rail where each face opens a viewer with timed progress bars, and its ring turns gray once the story has been seen.

## Rules

- antuikit components are COPIED into a project from a registry. There is no
  `antuikit` package to import components from at runtime.
- Import from `@/components/ui/avatar`, never from `antd`. antd stays for
  `theme`, `App`, the `message` / `notification` statics and type-only imports.
- Do not nest a bare `<ConfigProvider theme>` to re-theme a region. Use
  `<ThemeScope theme={...}>`, which also carries the cssVar key class that
  non-antd descendants inherit their tokens from.
- Colors, radii and spacing come from the token contract, not from hardcoded
  values: write `rounded-lg`, `px-xxs`, `bg-warning`, not the raw `var(--ant-*)`.
- `Avatar` takes every Ant Design v6 prop of the same component. The
  wrapper never narrows that surface, so anything antd documents also works here.