Getting Started
App Providerglobal.d.tsThemesTypes
cn(...args)Text ParserUnits Converters
AnchorAvatarBreadcrumbBurgerButtonCardCarouselCheckerCodeColor PickerCommandConfettiCopyButtonDouble Helix WordsFloating IndicatorGroupHighlight TextIndicatorInputKbdLabelLoaderPaginationPassword RequirementPolymorphic SlotProgressProseRatingRunning AreaScroll AreaSheetsSkeletonSliderStackSvgTableTabsTextareaTimelineTimesToasterTooltipTyping WordsTypography
useClickOutsideuseClipboarduseDeviceInfouseDialoguseDidUpdateuseDirectionuseDisclosureuseDocumentTitleuseDocumentVisibilityuseElementInfouseEyeDropperuseFetchuseFullscreenuseGeoLocationuseHotkeysuseHoveruseIduseImagePopupuseInputStateuseIntersectionuseIntervaluseIsomorphicEffectuseListStateuseLocalStorageuseMeasureScrollbaruseMediaQueryuseMergedRefuseMouseuseMoveuseMutationObserveruseNetworkuseOpenStateuseOrientationuseOSusePaginationusePWAInstalleruseRandomColorsuseReducedMotionuseReloaduseResizeObserveruseScrollIntoViewuseStateHistoryuseTimeoutuseTouchuseTriggeruseUncontrolleduseValidatedStateuseViewportSizeuseWindowEventuseWindowScroll
Docs
Web
Components
Avatar
Anchor

A simple anchor element that allows seamless navigation across different sections or external URLs.

Breadcrumb

A navigation aid that shows the user's path within a website or application, improving user experience.

Edit this page on GitHub
  • Started
  • Utilities
  • Configuration
  • Components
  • Hooks
  • Examples
  • Github
  • Contributing
⌘+J

© 2025 oeri rights MIT

Designed in Earth-616

Built by oeri

Avatar

A component used to display user profile images or placeholders. Can be customized with text, icons, or images.

Usage

Basic usage example to quickly see how the Avatar works.

BFit's me

K

MI
X
import { Group } from "@/ui/group";
import { StarIcon } from "@/icons/*";
import { Avatar } from "@/ui/avatar";

export function AvatarsDemo() {
  return (
    <Group justify="center">
      {/* With image and fallback */}
      <Avatar src="avatar.png" alt="it's me" fallback="Brian and friends" />

      {/* Default placeholder */}
      <Avatar round="12" />

      {/* Fallback Element Only */}
      <Avatar fallback={<p className="font-sans text-2xl font-extrabold italic">K</p>} />

      {/* Letters with xl radius */}
      <Avatar color="hsl(var(--constructive)/0.5)" round="12">
        Mike
      </Avatar>

      {/* Custom placeholder with fallback */}
      <Avatar color="blue" round="8" fallback="x">
        <StarIcon size="1.5rem" />
      </Avatar>
    </Group>
  );
}

Properties

Interactive configurator to explore customization options for the Avatar component.

Initial limit
Size
Round
Color
import { Avatar } from "@/ui/avatar";

export function AvatarDemo() {
  return <Avatar src="" />;
}

Avatar.Group

Displays multiple avatars grouped together, often used to represent a collection of users or entities. Automatically manages overlapping, spacing, and responsive behavior.

4N
BF
OL
Y
+999
Initial limit
Round
Size
Gap
Color
import { Avatar } from "@/ui/avatar";

export function AvatarGroupDemo() {
  return (
    <Avatar.Group>
      <Avatar fallback="4ndrea" src="https://api.dicebear.com/9.x/adventurer-neutral/svg?seed=Andrea" />
      <Avatar fallback="Brian and Frend Paual" src="https://api.dicebear.com/9.x/adventurer-neutral/svg?seed=Brian" />
      <Avatar fallback="oliver" src="/null.png" />
      <Avatar fallback="y" src="https://api.dicebear.com/9.x/adventurer-neutral/svg?seed=y" />
      <Avatar initialLimit="4">+9999</Avatar>
    </Avatar.Group>
  );
}

Use Avatar.Group when you need to show a team, participants, or related profiles compactly and clearly.

API References

Styles API

type T = "root" | "group" | "image" | "fallback";
Styles APITypeDefaultAnnotation
unstyled?Partial<Record<T, boolean>>falseif true, all default styles will be removed
classNames?Partial<Record<T, string>>undefinedSet className for T
styles?Partial<Record<T, CSSProperties>>undefinedSet style for T

Props API

Styles APITypeDefaultAnnotation
size?number | ${number}38Width and height of the avatar, numbers are converted to rem
round?(string & {}) | number9999Key of CSS value to set border-radius.
color?CSSProperties["color"] | "initials"grayKey of CSS color.
src?ImageProps["src"] | nullundefinedImage url, if the image cannot be loaded or src={null}, then fallback is displayed instead
alt?stringundefinedImage alt attribute, also used as title attribute for fallback
imageProps?ImgPropsundefined<NextImage/> tag attributes
children?React.ReactNodenullAvatar placeholder, displayed when src={null} or when the image cannot be loaded.
fallback?React.ReactNodenullA fallback tree to show when a Avatar src suspends.
name?stringinitialsName of the user. When src is not set, used to display initials and to generate color.
allowedInitialsColors?CSSProperties["color"][]undefinedAn array of colors that can be used for autogenerated initials

Source Codes

Full working code example, including necessary markup and styles. You can copy and paste this code directly to start using the component immediately.

avatar.tsx