Soon UI Design

Layout
Navigation
Input
Select
Display
Feedback

Avatar

사용자나 사물을 표현하는데 사용되는 아바타 컴포넌트입니다.

import { Avatar } from 'sud-ui';

GitHub에서 소스코드 보기

사용할 때

사용자나 사물을 이미지, 아이콘, 문자로 표현할 때

사용예제

Basic Usage

기본적인 사용방법입니다.

circle

square

rounded

Shape

아바타의 모양을 설정할 수 있습니다.

import React, { useState } from 'react';
import { Avatar, Radio, Card } from 'sud-ui';

const ShapeAvatar = () => {
  const [shape, setShape] = useState('circle');

  const shapeOptions = [
    { label: 'circle', value: 'circle' },
    { label: 'square', value: 'square' },
    { label: 'rounded', value: 'rounded' }
  ];

  return (
    <div className="flex flex-col gap-[20px]">
      <Card style={{ width: "100%" }} shadow="none" colorType="sub">
        <div className="flex justify-center w-full">
          <Radio.Group
            options={shapeOptions}
            direction="horizontal"
            value={shape}
            onChange={setShape}
          />
        </div>
      </Card>
      <div>
        <Avatar shape={shape} />
      </div>
    </div>
  );
};

export default ShapeAvatar;

Sample Image

아바타의 샘플 이미지를 설정할 수 있습니다.

김

이

박

클릭하거나 Enter/Space 키를 눌러보세요.

Interactive

아바타의 클릭 이벤트와 키보드 이벤트를 설정할 수 있습니다.

import React from 'react';
import { Avatar, Typography, toast } from 'sud-ui';

const InteractiveAvatar = () => {
  const handleClick = () => {
    toast.success('아바타를 클릭했습니다!');
  };

  const handleKeyDown = (e) => {
    console.log('Key pressed:', e.key);
  };

  return (
    <div className="flex flex-col gap-[20px]">
      <div className="flex gap-[20px] flex-wrap">
        <Avatar 
          src="김군순" 
          onClick={handleClick}
          onKeyDown={handleKeyDown}
          colorType="blue"
        />
        <Avatar 
          src="이순신" 
          onClick={handleClick}
          onKeyDown={handleKeyDown}
          colorType="green"
        />
        <Avatar 
          src="박영희" 
          onClick={handleClick}
          onKeyDown={handleKeyDown}
          colorType="orange"
        />
      </div>
      <Typography size="sm">
        클릭하거나 Enter/Space 키를 눌러보세요.
      </Typography>
    </div>
  );
};

export default InteractiveAvatar;

Shadow

아바타의 그림자를 설정할 수 있습니다.

김

이

김

이

Group

아바타의 그룹을 설정할 수 있습니다.

import React from 'react';
import { Avatar } from 'sud-ui';

const GroupAvatar = () => {
  const avatars = [
    { src: "김군순" },
    { src: "https://example.com/image.jpg", colorType: "blue" },
    { src: "이순신", colorType: "red" },
    { sample: 1 },
    { sample: 2 },
    { sample: 3 },
    { sample: 4 }
  ];

  return (
    <div className="flex flex-col gap-[20px]">
      <Avatar.Group max={3} gap={0.3} avatars={avatars} />
      <Avatar.Group max={3} gap={0.8} avatars={avatars} />
    </div>
  );
};

export default GroupAvatar;

Size

아바타의 크기를 설정할 수 있습니다.

import React, { useState } from 'react';
import { Avatar, Radio, Card, Input, Typography } from 'sud-ui';

const SizeAvatar = () => {
  const [size, setSize] = useState('md');
  const [sizeNumber, setSizeNumber] = useState(20);

  const sizeOptions = [
    { label: 'xs', value: 'xs' },
    { label: 'sm', value: 'sm' },
    { label: 'md', value: 'md' },
    { label: 'lg', value: 'lg' },
    { label: 'xl', value: 'xl' }
  ];

  return (
    <div className="flex flex-col gap-[20px]">
      <Card style={{ width: "100%" }} shadow="none" colorType="sub">
        <div className="flex flex-col items-center justify-center gap-[20px]">
          <Radio.Group
            options={sizeOptions}
            direction="horizontal"
            value={size}
            onChange={setSize}
          />
          <Input
            value={sizeNumber}
            size="sm"
            type="number"
            onChange={(e) => setSizeNumber(Number(e.target.value) || 0)}
            placeholder="숫자로 입력"
          />
        </div>
      </Card>
      <div className="flex gap-[10px]">
        <Card style={{ width: "100%" }} shadow="none">
          <div className="flex flex-col items-center justify-center gap-[10px]">
            <Avatar size={size} />
            <Typography>size Map</Typography>
          </div>
        </Card>
        <Card style={{ width: "100%" }} shadow="none">
          <div className="flex flex-col items-center justify-center gap-[10px]">
            <Avatar size={sizeNumber} />
            <Typography>size Number</Typography>
          </div>
        </Card>
      </div>
    </div>
  );
};

export default SizeAvatar;

Color Custom

아바타의 색을 설정할 수 있습니다.

김

Text & Icon

아바타의 텍스트와 아이콘을 설정할 수 있습니다.

Border

아바타의 테두리 스타일을 설정할 수 있습니다.

import React from 'react';
import { Avatar } from 'sud-ui';

const BorderAvatar = () => {
  return (
    <div className="flex gap-[20px] flex-wrap">
      <Avatar border borderType="solid" borderWeight={1} borderColor="blue-5" />
      <Avatar border borderType="dashed" borderWeight={2} borderColor="red-5" />
      <Avatar border borderType="dotted" borderWeight={3} borderColor="green-5" />
    </div>
  );
};

export default BorderAvatar;

SUD

Children

children을 사용하여 아바타 내부에 커스텀 콘텐츠를 넣을 수 있습니다.

import React from 'react';
import { Avatar, Typography } from 'sud-ui';
import { UserFill } from 'sud-icons';

const ChildrenAvatar = () => {
  return (
    <div className="flex gap-[20px] flex-wrap">
      <Avatar colorType="blue">
        <UserFill />
      </Avatar>
      <Avatar colorType="volcano">
        <UserFill />
      </Avatar>
      <Avatar colorType="green">
        <Typography pretendard="Black">SUD</Typography>
      </Avatar>
      <Avatar colorType="purple">
        <Typography pretendard="Black">AB</Typography>
      </Avatar>
    </div>
  );
};

export default ChildrenAvatar;

사용 방법

컴포넌트의 props를 설정하는 방법입니다.

src

아바타 이미지의 URL 또는 ReactNode. 문자열인 경우 첫 글자만 표시됩니다.

string | ReactNode

sample

샘플 이미지 번호 (1-5)

1 | 2 | 3 | 4 | 5

alt

이미지 대체 텍스트 (접근성)

string

avatar

children

이미지 대신 내부에 표시할 자식 요소

ReactNode

size

아바타의 크기

or number

shape

아바타의 모양

square

circle

rounded

capsule

circle

colorType

아바타의 색상 타입

default

red

rose

coral

orange

volcano

apricot

yellow

gold

amber

green

lime

mint

blue

sky

cerulean

indigo

cobalt

navy

purple

plum

orchid

forest

sage

warm-gray

cool-gray

neutral

default

background

배경색(palette값 또는 HEX code)

string

color

텍스트 색상(palette값 또는 HEX code)

string

border

테두리 표시 여부

boolean

false

borderColor

테두리 색상(palette값 또는 HEX code)

string

borderType

테두리 스타일

solid

dashed

dotted

double

groove

ridge

inset

outset

none

solid

borderWeight

테두리 두께 (px)

number

shadow

그림자 크기

none

className

추가 클래스명

string

style

추가 스타일

React.CSSProperties

{}

onClick

클릭 이벤트 핸들러 (클릭 가능한 아바타)

() => void

onKeyDown

키보드 이벤트 핸들러 (Enter, Space 키 지원)

(e: KeyboardEvent<HTMLDivElement>) => void

tabIndex

탭 인덱스 (onClick이 있을 때만 적용)

number

Avatar.Group

avatars

아바타 배열

Array<Partial<AvatarProps>>

[]

max

최대 표시 개수 (초과 시 +N 형태로 표시)

number

size

아바타의 크기

shape

아바타의 모양

square

circle

rounded

capsule

circle

colorType

아바타의 색상 타입

default

red

rose

coral

orange

volcano

apricot

yellow

gold

amber

green

lime

mint

blue

sky

cerulean

indigo

cobalt

navy

purple

plum

orchid

forest

sage

warm-gray

cool-gray

neutral

default

background

배경색(palette값 또는 HEX code)

string

color

텍스트 색상(palette값 또는 HEX code)

string

border

테두리 표시 여부

boolean

false

borderColor

테두리 색상(palette값 또는 HEX code)

string

borderType

테두리 스타일

solid

dashed

dotted

double

groove

ridge

inset

outset

none

solid

borderWeight

테두리 두께 (px)

number

shadow

그림자 크기

none

className

추가 클래스명

string

style

추가 스타일

React.CSSProperties

{}

zIndexStart

z-index 시작 값 (겹침 순서 조정)

number

gap

아바타 간의 겹침 정도 (0~1 사이의 값, 0에 가까울수록 많이 겹침)

number

0.6

aria-label

접근성 레이블

string

아바타 그룹

개인정보 처리방침

서비스 약관