ActionIcon

ActionIcon

아이콘 버튼 컴포넌트예요. 다형성(polymorphic) 컴포넌트로, 아이콘이나 단순한 시각적 요소를 담는 버튼을 만들 때 사용해요.

출처: 문서

본문

Usage

import { ActionIcon } from '@mantine/core';
import { SlidersHorizontalIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <ActionIcon variant="light" size="lg" aria-label="Settings">
      <SlidersHorizontalIcon />
    </ActionIcon>
  );
}

Gradient variant

variant prop이 gradient이면 gradient prop으로 그라디언트를 제어할 수 있어요. gradient prop은 from, to, deg 속성을 가진 객체를 받아요. gradient prop이 설정되지 않으면 ActionIcon은 theme object에서 설정할 수 있는 theme.defaultGradient을 사용해요. variant가 gradient가 아니면 gradient prop은 무시돼요.

variant="gradient"은 두 가지 색상의 선형 그라디언트만 지원해요. 더 복잡한 그라디언트가 필요하면 Styles API로 ActionIcon 스타일을 수정하세요.

Size

size prop에 유효한 CSS 값을 사용할 수 있으며 width, min-width, min-height, height 속성을 설정해요. size prop은 자식 icon 크기를 제어하지 않으므로 아이콘 컴포넌트에 직접 설정해야 해요. size가 숫자이면 px 단위로 취급되어 rem으로 변환돼요.

ActionIcon이 Mantine 입력과 같은 크기가 되게 하려면 size="input-sm" prop을 사용하세요.

Disabled state

ActionIcon을 비활성화하려면 disabled prop을 설정하세요. 버튼과의 모든 상호작용을 막고 비활성화 스타일을 추가해요. 버튼이 비활성화된 것처럼만 보이되 상호작용은 유지하려면 대신 data-disabled prop을 설정하세요. 비활성화 스타일은 모든 배리언트에서 동일해요.

Disabled state when ActionIcon is link

<a> 요소는 disabled 속성을 지원하지 않아요. ActionIcon이 링크로 렌더링될 때 비활성화하려면 data-disabled 속성을 설정하고 onClick 이벤트 핸들러에서 기본 동작을 방지하세요.

Customize disabled styles

비활성화 스타일을 커스터마이즈하려면 &:disabled와 &[data-disabled] 셀렉터를 둘 다 사용하는 것이 권장돼요.

• &:disabled – disabled prop이 설정된 버튼과 부모 컴포넌트에 의해 비활성화된 버튼(예: ActionIcon을 포함하는 <fieldset>에 disabled가 설정된 경우)을 스타일링
• &[data-disabled] – 실제로는 비활성화되지 않았지만 그렇게 보여야 하는 버튼(예: 비활성화된 ActionIcon에 Tooltip을 사용하거나 링크로 사용될 때 data-disabled 사용)

Demo.module.css
.button {
  &:disabled,
  &[data-disabled] {
    border-color: light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-4));
    background-color: transparent;
  }
}

Disabled button with Tooltip

ActionIcon이 비활성화되면 onMouseLeave 이벤트가 트리거되지 않아서 비활성화된 ActionIcon에 Tooltip을 사용하려면 disabled 대신 data-disabled prop을 설정해야 해요. ActionIcon이 실제로 비활성화되지 않아 onClick 이벤트가 여전히 발생하므로 onClick 이벤트 핸들러도 (event) => event.preventDefault()로 바꿔야 해요.

Loading state

loading prop을 설정하면 ActionIcon이 비활성화되고 버튼 중앙에 오버레이가 있는 Loader가 렌더링돼요. Loader 색상은 ActionIcon 배리언트에 따라 달라져요.

Loader props

loaderProps prop으로 Loader를 커스터마이즈할 수 있어요. Loader 컴포넌트가 가진 모든 props를 받아요.

Add custom variants

data-variant 속성으로 새 ActionIcon 배리언트를 추가할 수 있어요. 보통 새 배리언트는 theme에 추가해 애플리케이션의 모든 ActionIcon 컴포넌트에서 사용할 수 있게 해요.

import { Group, ActionIcon, MantineProvider, createTheme } from '@mantine/core';
import { HeartIcon } from '@phosphor-icons/react';
import classes from './Demo.module.css';

const theme = createTheme({
  components: {
    ActionIcon: ActionIcon.extend({
      classNames: classes,
    }),
  },
});

function Demo() {
  return (
    <MantineProvider theme={theme}>
      <ActionIcon variant="myVariant" size="xl"><HeartIcon /></ActionIcon>
    </MantineProvider>
  );
}

Customize variants colors

ActionIcon과 다른 컴포넌트 배리언트의 색은 variantColorResolver를 테마에 추가해 커스터마이즈할 수 있어요.

autoContrast

ActionIcon은 autoContrast prop과 theme.autoContrast를 지원해요. ActionIcon이나 테마에 autoContrast가 설정되면 color prop에 지정된 값과 충분한 대비를 이루도록 콘텐츠 색이 조정돼요.

autoContrast 기능은 color prop으로 배경색을 바꿀 때만 동작해요. autoContrast는 filled 배리언트에서만 동작해요.

Add custom sizes

ActionIcon 크기는 --ai-size-{x} CSS 변수로 정의돼요. 새 크기를 추가하는 가장 쉬운 방법은 root 요소에 추가 --ai-size-{x} 변수를 정의하는 것이에요.

ActionIcon.Group

ActionIcon.Group은 role="group"으로 렌더링돼요. 그룹이 의미 있는 작업 집합을 나타낸다면 aria-label(또는 aria-labelledby)로 접근 가능한 이름을 부여해 스크린 리더가 그 목적을 안내하게 하세요.

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

function Demo() {
  return (
    <ActionIcon.Group aria-label="Text formatting">
      {/* ...ActionIcon components */}
    </ActionIcon.Group>
  );
}

자식 ActionIcon 컴포넌트를 추가 요소로 감싸면 안 된다는 점에 주의하세요.

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

// Will not work correctly
function Demo() {
  return (
    <ActionIcon.Group>
      <div>This will not work</div>
      ActionIcons will have incorrect borders
    </ActionIcon.Group>
  );
}

ActionIcon.GroupSection

ActionIcon.GroupSection 컴포넌트로 ActionIcon.Group 안에 ActionIcon이 아닌 섹션을 렌더링할 수 있어요.

import { CaretDownIcon, CaretUpIcon } from '@phosphor-icons/react';
import { ActionIcon } from '@mantine/core';
import { useCounter } from '@mantine/hooks';

function Demo() {
  const [value, { increment, decrement }] = useCounter(135, { min: 0 });

  return (
    <ActionIcon.Group>
      <ActionIcon onClick={decrement}><CaretDownIcon /></ActionIcon>
      <ActionIcon.GroupSection>{value}</ActionIcon.GroupSection>
      <ActionIcon onClick={increment}><CaretUpIcon /></ActionIcon>
    </ActionIcon.Group>
  );
}

Polymorphic component

ActionIcon은 다형성 컴포넌트예요. 기본 루트 요소는 button이지만 component prop으로 다른 요소나 컴포넌트로 바꿀 수 있어요.

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

function Demo() {
  return <ActionIcon component="a" href="https://mantine.dev" target="_blank" aria-label="Open Mantine website" />;
}

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

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

function Demo() {
  return <ActionIcon component={Link} href="/" aria-label="Home" />;
}

Polymorphic components with TypeScript

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

다형성이 아닌(즉 component prop을 지원하지 않는) 다형성 컴포넌트의 래퍼를 만들려면 컴포넌트 props 인터페이스가 HTML 요소 props를 확장해야 해요. 예를 들어:

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

interface MyActionIconProps extends ActionIconProps,
  ElementProps<'button'> {}

래핑 후에도 컴포넌트가 다형성을 유지하려면 이 가이드에 설명된 polymorphic 함수를 사용하세요.

Get element ref

import { useRef } from 'react';
import { ActionIcon } from '@mantine/core';

function Demo() {
  const ref = useRef<HTMLButtonElement>(null);
  return <ActionIcon ref={ref} aria-label="Button" />;
}

Accessibility

ActionIcon을 스크린 리더가 접근할 수 있게 하려면 aria-label을 설정하거나 VisuallyHidden 컴포넌트를 사용해야 해요.

import { HeartIcon } from '@phosphor-icons/react';
import { ActionIcon, VisuallyHidden } from '@mantine/core';

function Demo() {
  return (
    <>
      <ActionIcon variant="subtle" aria-label="Like post"><HeartIcon /></ActionIcon>
      <ActionIcon variant="subtle">
        <HeartIcon />
        <VisuallyHidden>Like post</VisuallyHidden>
      </ActionIcon>
    </>
  );
}

더 알아보기 (Learn more)

• TreeSelect
• Button