Avatar

Avatar (아바타)

Avatar는 사용자나 대상을 나타내는 원형(기본) 또는 사각형 이미지·아이콘·문자 컴포넌트예요.

출처: 문서

본문

예제 (Examples)

기본 (Basic)

세 가지 크기와 두 가지 모양을 사용할 수 있어요.

import React from 'react';
import { UserOutlined } from '@ant-design/icons';
import { Avatar, Space } from 'antd';

const App: React.FC = () => (
  <Space vertical size={16}>
    <Space wrap size={16}>
      <Avatar size={64} icon={<UserOutlined />} />
      <Avatar size="large" icon={<UserOutlined />} />
      <Avatar icon={<UserOutlined />} />
      <Avatar size="small" icon={<UserOutlined />} />
      <Avatar size={14} icon={<UserOutlined />} />
    </Space>
    <Space wrap size={16}>
      <Avatar shape="square" size={64} icon={<UserOutlined />} />
      <Avatar shape="square" size="large" icon={<UserOutlined />} />
      <Avatar shape="square" icon={<UserOutlined />} />
      <Avatar shape="square" size="small" icon={<UserOutlined />} />
      <Avatar shape="square" size={14} icon={<UserOutlined />} />
    </Space>
  </Space>
);

export default App;

타입 (Type)

이미지, 아이콘, 문자를 지원하고, 뒤의 두 종류 아바타는 색과 배경색을 커스터마이즈할 수 있어요.

import React from 'react';
import { UserOutlined } from '@ant-design/icons';
import { Avatar, Space } from 'antd';

const url = 'https://gw.alipayobjects.com/zos/rmsportal/KDpgvguMpGfqaHPjicRK.svg';

const App: React.FC = () => (
  <Space size={16} wrap>
    <Avatar icon={<UserOutlined />} />
    <Avatar>U</Avatar>
    <Avatar size={40}>USER</Avatar>
    <Avatar src={url} />
    <Avatar src={<img draggable={false} src={url} alt="avatar" />} />
    <Avatar style={{ backgroundColor: '#fde3cf', color: '#f56a00' }}>U</Avatar>
    <Avatar style={{ backgroundColor: '#87d068' }} icon={<UserOutlined />} />
  </Space>
);

export default App;

폰트 크기 자동 설정 (Autoset Font Size)

문자 타입 아바타에서 문자가 너무 길어 표시가 어려울 때, 폰트 크기를 아바타 너비에 맞춰 자동 조절할 수 있어요. gap으로 좌우 사이의 단위 거리를 설정할 수도 있어요.

import React, { useState } from 'react';
import { Avatar, Button } from 'antd';

const UserList = ['U', 'Lucy', 'Tom', 'Edward'];
const ColorList = ['#f56a00', '#7265e6', '#ffbf00', '#00a2ae'];
const GapList = [4, 3, 2, 1];

const App: React.FC = () => {
  const [user, setUser] = useState(UserList[0]);
  const [color, setColor] = useState(ColorList[0]);
  const [gap, setGap] = useState(GapList[0]);

  const changeUser = () => {
    const index = UserList.indexOf(user);
    setUser(index < UserList.length - 1 ? UserList[index + 1] : UserList[0]);
    setColor(index < ColorList.length - 1 ? ColorList[index + 1] : ColorList[0]);
  };

  const changeGap = () => {
    const index = GapList.indexOf(gap);
    setGap(index < GapList.length - 1 ? GapList[index + 1] : GapList[0]);
  };

  return (
    <>
      <Avatar style={{ backgroundColor: color, verticalAlign: 'middle' }} size="large" gap={gap}>
        {user}
      </Avatar>
      <Button
        size="small"
        style={{ margin: '0 16px', verticalAlign: 'middle' }}
        onClick={changeUser}
      >
        ChangeUser
      </Button>
      <Button size="small" style={{ verticalAlign: 'middle' }} onClick={changeGap}>
        changeGap
      </Button>
    </>
  );
};

export default App;

Badge와 함께 (With Badge)

보통 알림과 통지에 사용돼요.

import React from 'react';
import { UserOutlined } from '@ant-design/icons';
import { Avatar, Badge, Space } from 'antd';

const App: React.FC = () => (
  <Space size={24}>
    <Badge count={1}>
      <Avatar shape="square" icon={<UserOutlined />} />
    </Badge>
    <Badge dot>
      <Avatar shape="square" icon={<UserOutlined />} />
    </Badge>
  </Space>
);

export default App;

Avatar.Group

아바타 그룹 표시예요.

import React from 'react';
import { AntDesignOutlined, UserOutlined } from '@ant-design/icons';
import { Avatar, Divider, Tooltip } from 'antd';

const App: React.FC = () => (
  <>
    <Avatar.Group>
      <Avatar src="https://api.dicebear.com/10.x/lorelei/svg?seed=1" />
      <a href="https://ant.design">
        <Avatar style={{ backgroundColor: '#f56a00' }}>K</Avatar>
      </a>
      <Tooltip title="Ant User" placement="top">
        <Avatar style={{ backgroundColor: '#87d068' }} icon={<UserOutlined />} />
      </Tooltip>
      <Avatar style={{ backgroundColor: '#1677ff' }} icon={<AntDesignOutlined />} />
    </Avatar.Group>
    <Divider />
    <Avatar.Group
      max={{
        count: 2,
        style: { color: '#f56a00', backgroundColor: '#fde3cf' },
      }}
    >
      <Avatar src="https://api.dicebear.com/10.x/lorelei/svg?seed=2" />
      <Avatar style={{ backgroundColor: '#f56a00' }}>K</Avatar>
      <Tooltip title="Ant User" placement="top">
        <Avatar style={{ backgroundColor: '#87d068' }} icon={<UserOutlined />} />
      </Tooltip>
      <Avatar style={{ backgroundColor: '#1677ff' }} icon={<AntDesignOutlined />} />
    </Avatar.Group>
    <Divider />
    <Avatar.Group
      size="large"
      max={{
        count: 2,
        style: { color: '#f56a00', backgroundColor: '#fde3cf' },
      }}
    >
      <Avatar src="https://api.dicebear.com/10.x/lorelei/svg?seed=3" />
      <Avatar style={{ backgroundColor: '#f56a00' }}>K</Avatar>
      <Tooltip title="Ant User" placement="top">
        <Avatar style={{ backgroundColor: '#87d068' }} icon={<UserOutlined />} />
      </Tooltip>
      <Avatar style={{ backgroundColor: '#1677ff' }} icon={<AntDesignOutlined />} />
    </Avatar.Group>
    <Divider />
    <Avatar.Group
      size="large"
      max={{
        count: 2,
        style: { color: '#f56a00', backgroundColor: '#fde3cf', cursor: 'pointer' },
        popover: { trigger: 'click' },
      }}
    >
      <Avatar src="https://zos.alipayobjects.com/rmsportal/ODTLcjxAfvqbxHnVXCYX.png" />
      <Avatar style={{ backgroundColor: '#f56a00' }}>K</Avatar>
      <Tooltip title="Ant User" placement="top">
        <Avatar style={{ backgroundColor: '#87d068' }} icon={<UserOutlined />} />
      </Tooltip>
      <Avatar style={{ backgroundColor: '#1677ff' }} icon={<AntDesignOutlined />} />
    </Avatar.Group>
    <Divider />
    <Avatar.Group shape="square">
      <Avatar style={{ backgroundColor: '#fde3cf' }}>A</Avatar>
      <Avatar style={{ backgroundColor: '#f56a00' }}>K</Avatar>
      <Avatar style={{ backgroundColor: '#87d068' }} icon={<UserOutlined />} />
      <Avatar style={{ backgroundColor: '#1677ff' }} icon={<AntDesignOutlined />} />
    </Avatar.Group>
  </>
);

export default App;

maxCount가 오버플로를 포함 (maxCount includes overflow)

Avatar.Group을 HOC로 감싸 overflowInFinal prop을 추가해요. 활성화하면 max.count는 표시할 총 요소 수를 뜻하고, 오버플로 표시를 위해 1개 슬롯을 남겨 둡니다.

import React, { useState } from 'react';
import { toArray } from '@rc-component/util';
import { Avatar, Flex, InputNumber, Switch } from 'antd';
import type { GetProps } from 'antd';

type AvatarGroupProps = GetProps<typeof Avatar.Group>;

const AvatarGroupOverflow: React.FC<AvatarGroupProps & { overflowInFinal?: boolean }> = (props) => {
  const { overflowInFinal, ...restProps } = props;
  const mergedMaxCount = props.max?.count ?? 3;
  const childrenCount = toArray(props.children).length;
  if (!overflowInFinal || mergedMaxCount >= childrenCount) {
    return <Avatar.Group {...restProps} />;
  }

  return (
    <Avatar.Group
      {...restProps}
      max={{
        ...props.max,
        count: Math.max(1, mergedMaxCount - 1),
      }}
    />
  );
};

const App: React.FC = () => {
  const [avatarCount, setAvatarCount] = useState(4);
  const [overflowInFinal, setOverflowInFinal] = useState(true);

  return (
    <Flex vertical gap="middle">
      <Flex gap={24}>
        <span>Avatar count: </span>
        <InputNumber
          style={{ width: 120 }}
          min={2}
          max={10}
          value={avatarCount}
          onChange={(value) => setAvatarCount(value!)}
          aria-label="Avatar count"
          mode="spinner"
        />
      </Flex>
      <Flex gap={8}>
        <span>overflowInFinal: </span>
        <Switch
          checked={overflowInFinal}
          onChange={setOverflowInFinal}
          aria-label="overflowInFinal"
        />
      </Flex>

      <AvatarGroupOverflow
        max={{
          count: 3,
          style: { backgroundColor: '#52c41a', color: '#fff' },
        }}
        overflowInFinal={overflowInFinal}
      >
        {Array.from({ length: avatarCount }, (_, i) => (
          <Avatar key={i} style={{ backgroundColor: '#f56a00' }}>
            {String.fromCharCode(65 + i)}
          </Avatar>
        ))}
      </AvatarGroupOverflow>
    </Flex>
  );
};

export default App;

반응형 크기 (Responsive Size)

Avatar 크기를 화면 크기에 따라 자동 조절할 수 있어요.

import React from 'react';
import { AntDesignOutlined } from '@ant-design/icons';
import { Avatar } from 'antd';

const App: React.FC = () => (
  <Avatar
    size={{ xs: 24, sm: 32, md: 40, lg: 64, xl: 80, xxl: 100 }}
    icon={<AntDesignOutlined />}
  />
);

export default App;

API

공통 props 참고: Common props

Avatar

팁: 이미지 로드 오류의 폴백으로 icon이나 children을 설정할 수 있어요. 우선순위는 icon > children이에요.

Avatar.Group 4.5.0+

디자인 토큰 (Design Token)

컴포넌트 토큰 (Avatar)

전역 토큰 (Global Token)

더 알아보기 (Learn more)

• Badge 컴포넌트 — 알림 표시
• Tooltip 컴포넌트 — 호버 설명
• Ant Design 시작하기 — 프로젝트 설정