Avatar

Avatar

사용자 프로필 이미지, 이니셜 또는 대체 아이콘을 표시하는 컴포넌트예요. 다형성(polymorphic) 컴포넌트로, 이미지가 없으면 이니셜이나 아이콘을 보여줘요.

출처: 문서

본문

Usage

import { Avatar } from '@mantine/core';
import { StarIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <>
      {/* With image */}
      <Avatar src="https://placehold.co/100" alt="it's me" />
      {/* Default placeholder */}
      <Avatar radius="xl" />
      {/* Letters with xl radius */}
      <Avatar color="cyan" radius="xl">MK</Avatar>
      {/* Custom placeholder icon */}
      <Avatar color="blue" radius="xl">
        <StarIcon />
      </Avatar>
    </>
  );
}

Initials

기본 대체 요소 대신 이니셜을 표시하려면 name prop에 사람의 이름을 설정하세요. 예를 들어 name="John Doe". 이름이 설정되면 color="initials"를 사용해 이름에 기반한 색을 생성할 수 있어요.

import { Avatar, Group } from '@mantine/core';

const names = [
  'John Doe',
  'Jane Mol',
  'Alex Lump',
  'Sarah Condor',
  'Mike Johnson',
  'Kate Kok',
  'Tom Smith',
];

function Demo() {
  const avatars = names.map((name) => <Avatar key={name} name={name} color="initials" />);
  return <Group>{avatars}</Group>;
}

Allowed initials colors

기본적으로 기본 테마의 모든 색이 이니셜에 허용돼요. allowedInitialsColors prop에 색 배열을 제공해 제한할 수 있어요. 기본 색 배열에는 테마에 정의된 커스텀 색이 포함되지 않으므로 필요하면 직접 제공해야 해요.

Placeholder

이미지를 불러올 수 없거나 제공되지 않으면 Avatar가 대신 대체 요소를 표시해요. 기본적으로 대체 요소는 아이콘이지만 어떤 React 노드로든 바꿀 수 있어요.

import { Avatar } from '@mantine/core';
import { StarIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <>
      {/* Default placeholder */}
      <Avatar />
      {/* Default placeholder with custom color */}
      <Avatar color="red" />
      {/* Placeholder with initials */}
      <Avatar color="teal" variant="light">VR</Avatar>
      {/* Placeholder with custom icon */}
      <Avatar color="indigo">
        <StarIcon />
      </Avatar>
    </>
  );
}

Variants

Avatar는 Filled/Light/Outline/Transparent/White/Default 배리언트와 radius, size, color, src 등 다양한 props를 지원해요.

Avatar.Group

Avatar.Group 컴포넌트는 여러 아바타를 스택으로 결합해요.

import { Avatar } from '@mantine/core';

function Demo() {
  return (
    <Avatar.Group>
      <Avatar src="https://placehold.co/100" alt="it's me" />
      <Avatar src="https://placehold.co/100" alt="it's me" />
      <Avatar color="blue" radius="xl">+5</Avatar>
    </Avatar.Group>
  );
}

자식 Avatar 컴포넌트를 추가 요소로 감싸면 안 된다는 점에 주의하지만, 현재 트리에서 HTML 요소를 렌더링하지 않는 컴포넌트(예: Tooltip)로는 Avatar를 감쌀 수 있어요.

import { Avatar } from '@mantine/core';

// Will not work correctly
function Demo() {
  return (
    <Avatar.Group>
      <div>
        <Avatar src="https://placehold.co/100" />
      </div>
      <Avatar color="blue" radius="xl">+5</Avatar>
    </Avatar.Group>
  );
}

Tooltip과 사용하는 예시:

import { Avatar, Tooltip } from '@mantine/core';

function Demo() {
  return (
    <Avatar.Group>
      <Tooltip label="John Outcast">
        <Avatar src="https://placehold.co/100" />
      </Tooltip>
      <Tooltip label="Levi Capitan">
        <Avatar src="https://placehold.co/100" />
      </Tooltip>
      <Avatar color="blue" radius="xl">+2</Avatar>
    </Avatar.Group>
  );
}

Polymorphic component

Avatar는 다형성 컴포넌트예요. 기본 루트 요소는 div이지만 component prop으로 바꿀 수 있어요.

import { Avatar } from '@mantine/core';

function Demo() {
  return <Avatar component="a" href="https://github.com/rtivital" />;
}

component prop에 컴포넌트도 사용할 수 있어요. 예를 들어 Next.js Link:

import Link from 'next/link';
import { Avatar } from '@mantine/core';

function Demo() {
  return <Avatar component={Link} href="/profile" />;
}

Polymorphic components with TypeScript

다형성 컴포넌트의 prop 타입은 일반 컴포넌트와 달라요. 기본 요소의 HTML 요소 props를 확장하지 않아요. 예를 들어 div가 기본 요소임에도 AvatarProps는 React.ComponentProps<'div'>를 확장하지 않아요.

다형성이 아닌 래퍼를 만들려면 props 인터페이스가 HTML 요소 props를 확장해야 해요.

import type { AvatarProps, ElementProps } from '@mantine/core';

interface MyAvatarProps extends AvatarProps,
  ElementProps<'div'> {}

래핑 후에도 다형성을 유지하려면 이 가이드의 polymorphic 함수를 사용하세요.

링크로 Avatar를 사용하는 예시:

import { Avatar } from '@mantine/core';

function Demo() {
  return (
    <Avatar component="a" href="https://github.com/rtivital" target="_blank">
      V
    </Avatar>
  );
}

Accessibility

Avatar는 <img> HTML 요소를 렌더링해요. alt prop을 설정해 이미지를 설명하세요. 이미지를 불러올 수 없을 때 아바타 대체 요소의 title 속성으로도 사용돼요.

import { Avatar } from '@mantine/core';

function Demo() {
  // ❌ No alt for image
  return <Avatar src="https://placehold.co/100" />;

  // ✅ alt is set
  return <Avatar src="https://placehold.co/100" alt="Person name" />;

  // ✅ title is not required, but still recommended
  return <Avatar name="RJ" />;

  // ✅ title is set on placeholder
  return <Avatar name="RJ" title="RJ" />;
}

더 알아보기 (Learn more)

• Accordion
• BackgroundImage