Component

Avatar

사람이나 조직의 이미지와 대체 내용을 표시합니다.

Playground

옵션을 조절하며 화면과 사용 코드를 함께 확인하세요.

PC 1280px

Controls

group을 끄고 withImage를 켜면 이미지 주소를 사용할 수 있습니다.

이미지와 fallback의 접근 가능한 이름

이미지가 없을 때 표시할 내용

avatar 크기

원형 avatar · 끄면 크기 비례 20% 모서리

group을 켜면 AvatarGroup에 적용됩니다.

AvatarGroup 표시

src를 넣어 이미지 표시

Code

import { AvatarGroup, Avatar } from '@amineslab/ui'

export default function ExamplePreview() {
  return ((<Avatar alt={"민서"} fallback={"민서"} rounded={false} size={"md"} src={undefined}/>))
}

Props

import {
  Avatar,
  AvatarRoot,
  AvatarImage,
  AvatarFallback,
  AvatarGroup,
} from '@amineslab/ui'

`Avatar`

Name	Type	Default	Description
`src`	`string`	-	표시할 이미지 주소입니다.
`alt`	`string`	`''`	이미지와 fallback의 접근 가능한 이름입니다.
`fallback`	`ReactNode`	-	이미지가 없을 때 표시할 내용입니다.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	avatar 크기입니다. Avatar.Group에 주면 자식 Avatar와 초과 개수 표시에 함께 적용하며 자식의 값이 우선합니다.
`rounded`	`boolean`	`false`	원형 avatar로 만듭니다. 기본은 크기에 비례하는 20% 모서리라 모든 size에서 같은 곡률입니다. Avatar.Group에 주면 자식 Avatar·테두리·초과 개수 표시에 함께 적용하며 자식의 값이 우선합니다.
`max`	`number`	-	Avatar.Group에서 표시할 최대 개수입니다.
`spacing`	`'tight' \| 'normal'`	`'tight'`	Avatar.Group의 겹침 정도입니다.
`overflowLabel`	`(hiddenCount: number) => string`	-	숨겨진 사람 수의 접근 가능한 이름을 만듭니다.

Examples

자주 쓰는 조합을 살펴보고, 필요한 예시의 코드를 펼쳐 확인하세요.

Sizes

import { type ComponentPropsWithoutRef } from 'react'

import { cn } from '@amineslab/ui/utils'

import { type ControlSize, Avatar } from '@amineslab/ui'

const controlSizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const satisfies readonly ControlSize[];

const avatarSizes = controlSizes;

function ExampleRow({ className, stretch = false, ...props }: ComponentPropsWithoutRef<'div'> & {
    stretch?: boolean;
}) {
    return (<div {...props} className={cn('flex flex-wrap justify-center gap-3', stretch ? 'items-stretch' : 'items-center', className)}/>);
}

export default function ExamplePreview() {
  return ((<ExampleRow>
          {avatarSizes.map((size) => (<Avatar alt="민서" fallback="민" key={size} size={size}/>))}
        </ExampleRow>))
}

Rounded

기본 모서리는 크기에 비례하는 20%라 모든 size에서 같은 곡률입니다.

import { type ComponentPropsWithoutRef } from 'react'

import { cn } from '@amineslab/ui/utils'

import { Avatar } from '@amineslab/ui'

function ExampleRow({ className, stretch = false, ...props }: ComponentPropsWithoutRef<'div'> & {
    stretch?: boolean;
}) {
    return (<div {...props} className={cn('flex flex-wrap justify-center gap-3', stretch ? 'items-stretch' : 'items-center', className)}/>);
}

export default function ExamplePreview() {
  return ((<ExampleRow>
          <Avatar alt="민서" fallback="민" size="lg"/>
          <Avatar alt="민서" fallback="민" rounded size="lg"/>
        </ExampleRow>))
}

Group

max를 넘는 사람 수는 overflowLabel로 접근 가능한 이름을 만듭니다.

import { AvatarGroup, Avatar } from '@amineslab/ui'

export default function ExamplePreview() {
  return ((<AvatarGroup max={3} overflowLabel={(count) => `${count}명 더`}>
          <Avatar alt="민서" fallback="민"/>
          <Avatar alt="지훈" fallback="지"/>
          <Avatar alt="수아" fallback="수"/>
          <Avatar alt="도윤" fallback="도"/>
          <Avatar alt="하은" fallback="하"/>
        </AvatarGroup>))
}

사용 기준

권장하는 사용

이미지가 없어도 식별 가능한 이니셜이나 대체 텍스트를 제공합니다.

피해야 할 사용

겉모양만으로 사용을 결정하지 마세요.
의미와 키보드 동작, 모바일에서의 흐름을 함께 확인하세요.

접근성

화면에 맞는 이름을 제공하고, 키보드만으로 작업을 마칠 수 있는지 확인하세요.

이 컴포넌트에는 별도의 키보드 조작이 필요하지 않습니다.