Alert

Alert (경고 알림)

Alert는 앱 사용을 방해하지 않으면서 사용자에게 짧은 메시지를 표시해 주는 컴포넌트예요.

출처: 문서

본문

소개 (Introduction)

Alert는 사용자에게 짧고 때로는 시간에 민감한 정보를 눈에 거슬리지 않는 방식으로 제공해 줘요.

Material UI Alert 컴포넌트는 그 내용에 대한 즉각적인 시각적 단서를 제공하도록 스타일을 빠르게 커스터마이즈할 수 있는 여러 props를 포함하고 있어요.

import Alert from '@mui/material/Alert';
import CheckIcon from '@mui/icons-material/Check';

export default function SimpleAlert() {
  return (
    <Alert icon={<CheckIcon fontSize="inherit" />} severity="success">
      Here is a gentle confirmation that your action was successful.
    </Alert>
  );
}

:::info 이 컴포넌트는 더 이상 Material Design 가이드라인에 문서화되어 있지 않지만, Material UI는 계속 지원할 거예요. :::

용도 (Usage)

alert 패턴의 핵심 특징은 앱을 사용하는 사용자 경험을 방해해서는 안 된다는 점이에요. Alert는 사용자에게 응답을 얻기 위해 의도적으로 개입하는 alert 다이얼로그(dialog, ARIA)와 혼동해서는 안 돼요. 이런 동작이 필요하다면 Material UI Dialog 컴포넌트를 사용하세요 (alert dialog 예시를 참고).

기초 (Basics)

import Alert from '@mui/material/Alert';

Alert 컴포넌트는 콘텐츠를 감싸며, 감싸고 있는 컨테이너를 채우도록 늘어나요.

심각도 (Severity)

severity prop은 서로 다른 상태를 나타내는 네 가지 값을 받아요 — success(기본값), info, warning, error — 각각에 해당하는 아이콘과 색상 조합이 준비되어 있어요:

import Alert from '@mui/material/Alert';
import Stack from '@mui/material/Stack';

export default function BasicAlerts() {
  return (
    <Stack sx={{ width: '100%' }} spacing={2}>
      <Alert severity="success">This is a success Alert.</Alert>
      <Alert severity="info">This is an info Alert.</Alert>
      <Alert severity="warning">This is a warning Alert.</Alert>
      <Alert severity="error">This is an error Alert.</Alert>
    </Stack>
  );
}

변형 (Variants)

Alert 컴포넌트에는 filled와 outlined 두 가지 대체 스타일 옵션이 있고, variant prop으로 설정할 수 있어요.

Filled

import Alert from '@mui/material/Alert';
import Stack from '@mui/material/Stack';

export default function FilledAlerts() {
  return (
    <Stack sx={{ width: '100%' }} spacing={2}>
      <Alert variant="filled" severity="success">
        This is a filled success Alert.
      </Alert>
      <Alert variant="filled" severity="info">
        This is a filled info Alert.
      </Alert>
      <Alert variant="filled" severity="warning">
        This is a filled warning Alert.
      </Alert>
      <Alert variant="filled" severity="error">
        This is a filled error Alert.
      </Alert>
    </Stack>
  );
}

Outlined

import Alert from '@mui/material/Alert';
import Stack from '@mui/material/Stack';

export default function OutlinedAlerts() {
  return (
    <Stack sx={{ width: '100%' }} spacing={2}>
      <Alert variant="outlined" severity="success">
        This is an outlined success Alert.
      </Alert>
      <Alert variant="outlined" severity="info">
        This is an outlined info Alert.
      </Alert>
      <Alert variant="outlined" severity="warning">
        This is an outlined warning Alert.
      </Alert>
      <Alert variant="outlined" severity="error">
        This is an outlined error Alert.
      </Alert>
    </Stack>
  );
}

:::warning Snackbar 컴포넌트와 함께 outlined Alert를 사용하면 기본적으로 뒤 배경 콘텐츠가 Alert를 통해 비쳐 보여요. 이를 막으려면 Alert 컴포넌트의 sx prop에 bgcolor: 'background.paper'를 추가하면 돼요:

<Alert sx={{ bgcolor: 'background.paper' }} />

이 두 컴포넌트를 함께 사용하는 예시는 Snackbar—customization 문서에서 확인할 수 있어요. :::

색상 (Color)

원하는 severity에 대한 기본 색상을 덮어쓰려면 color prop을 사용하세요 — 예를 들어 success Alert에 warning 색상을 적용한다거나:

import Alert from '@mui/material/Alert';

export default function ColorAlerts() {
  return (
    <Alert severity="success" color="warning">
      This is a success Alert with warning colors.
    </Alert>
  );
}

동작 (Actions)

action prop으로 Alert에 동작(action)을 추가할 수 있어요. 이를 통해 Alert의 메시지 뒤, 오른쪽 정렬된 위치에 어떤 요소든 삽입할 수 있어요 — HTML 태그, SVG 아이콘, 또는 Material UI Button 같은 React 컴포넌트 등이요.

action prop을 설정하지 않은 채 Alert에 onClose 콜백을 제공하면, 컴포넌트는 기본적으로 닫기 아이콘(✕)을 표시해요.

import Alert from '@mui/material/Alert';
import Button from '@mui/material/Button';
import Stack from '@mui/material/Stack';

export default function ActionAlerts() {
  return (
    <Stack sx={{ width: '100%' }} spacing={2}>
      <Alert severity="warning" onClose={() => {}}>
        This Alert displays the default close icon.
      </Alert>
      <Alert
        severity="success"
        action={
          <Button color="inherit" size="small">
            UNDO
          </Button>
        }
      >
        This Alert uses a Button component for its action.
      </Alert>
    </Stack>
  );
}

아이콘 (Icons)

icon prop으로 Alert의 아이콘을 덮어쓸 수 있어요. action prop처럼 icon도 HTML 요소, SVG 아이콘, React 컴포넌트가 될 수 있어요. 이 prop을 false로 설정하면 아이콘을 완전히 제거할 수 있어요.

주어진 severity에 대한 아이콘 인스턴스 전체를 덮어써야 한다면 iconMapping prop을 대신 사용할 수 있어요. 이 prop은 앱의 테마를 커스터마이즈해 전역적으로 정의할 수 있어요. 자세한 내용은 Theme components—Default props를 참고해 주세요.

import Alert from '@mui/material/Alert';
import CheckIcon from '@mui/icons-material/Check';
import CheckCircleOutlineIcon from '@mui/icons-material/CheckCircleOutlined';
import Stack from '@mui/material/Stack';

export default function IconAlerts() {
  return (
    <Stack sx={{ width: '100%' }} spacing={2}>
      <Alert icon={<CheckIcon fontSize="inherit" />} severity="success">
        This success Alert has a custom icon.
      </Alert>
      <Alert icon={false} severity="success">
        This success Alert has no icon.
      </Alert>
      <Alert
        iconMapping={{
          success: <CheckCircleOutlineIcon fontSize="inherit" />,
        }}
      >
        This success Alert uses `iconMapping` to override the default icon.
      </Alert>
    </Stack>
  );
}

커스터마이즈 (Customization)

제목 (Titles)

Alert에 제목을 추가하려면 Alert Title 컴포넌트를 import 하세요:

import AlertTitle from '@mui/material/AlertTitle';

이 컴포넌트를 Alert의 메시지 위에 중첩하면 아래처럼 깔끔하게 스타일되고 제대로 정렬된 제목을 만들 수 있어요:

import Alert from '@mui/material/Alert';
import AlertTitle from '@mui/material/AlertTitle';
import Stack from '@mui/material/Stack';

export default function DescriptionAlerts() {
  return (
    <Stack sx={{ width: '100%' }} spacing={2}>
      <Alert severity="success">
        <AlertTitle>Success</AlertTitle>
        This is a success Alert with an encouraging title.
      </Alert>
      <Alert severity="info">
        <AlertTitle>Info</AlertTitle>
        This is an info Alert with an informative title.
      </Alert>
      <Alert severity="warning">
        <AlertTitle>Warning</AlertTitle>
        This is a warning Alert with a cautious title.
      </Alert>
      <Alert severity="error">
        <AlertTitle>Error</AlertTitle>
        This is an error Alert with a scary title.
      </Alert>
    </Stack>
  );
}

전환 (Transitions)

Transition 컴포넌트 — 예를 들어 Collapse — 를 사용해 Alert의 등장과 퇴장에 움직임을 더할 수 있어요.

import * as React from 'react';
import Box from '@mui/material/Box';
import Alert from '@mui/material/Alert';
import IconButton from '@mui/material/IconButton';
import Collapse from '@mui/material/Collapse';
import Button from '@mui/material/Button';
import CloseIcon from '@mui/icons-material/Close';

export default function TransitionAlerts() {
  const [open, setOpen] = React.useState(true);

  return (
    <Box sx={{ width: '100%' }}>
      <Collapse in={open}>
        <Alert
          action={
            <IconButton
              aria-label="close"
              color="inherit"
              size="small"
              onClick={() => {
                setOpen(false);
              }}
            >
              <CloseIcon fontSize="inherit" />
            </IconButton>
          }
          sx={{ mb: 2 }}
        >
          Click the close icon to see the Collapse transition in action!
        </Alert>
      </Collapse>
      <Button
        disabled={open}
        variant="outlined"
        onClick={() => {
          setOpen(true);
        }}
      >
        Re-open
      </Button>
    </Box>
  );
}

접근성 (Accessibility)

Alert가 접근성을 확보하도록 고려해야 할 몇 가지 사항이 있어요:

alert는 앱 사용을 방해하지 않기 위한 것이므로 Alert 컴포넌트는 절대로 키보드 포커스에 영향을 주면 안 돼요.
alert에 동작(action)이 들어 있다면, 그 동작은 키보드만 사용하는 사용자가 도달할 수 있도록 tabindex가 0이어야 해요.
필수적인 alert는 자동으로 사라지게 해서는 안 돼요 — 시간 제한 상호작용(timed interactions)은 alert를 이해하거나 찾는 데 추가 시간이 필요한 사용자들에게 앱을 사용할 수 없게 만들 수 있어요.
기본적으로 Alert는 role="alert"인 요소를 렌더링해요. 이는 aria-live="assertive"와 aria-atomic="true"를 사용하는 것과 같아요. 이는 메시지가 사용자의 즉각적인 주의를 필요로 한다고 가정하는 거예요. 덜 긴급한 메시지는 덜 공격적인 방법—예를 들어 기본 role을 role="status"로 덮어쓰는 것—을 사용해야 해요. 더 자세한 내용은 이 alert role 페이지를 확인해 주세요.
너무 자주 발생하는 Alert는 앱의 사용성을 저해할 수 있어요.
동적으로 렌더링된 alert는 화면 판독기(screen reader)가 알려주지만, 페이지가 로드될 때 이미 존재하는 alert는 알려주지 않아요.
색상은 보조 기술(assistive technology)을 필요로 하는 사용자에게 UI에 의미를 더해 주지 않아요. 색상을 통해 전달되는 모든 정보는 alert 자체의 텍스트나, 화면 판독기가 읽어주는 추가 숨김 텍스트 등 다른 방식으로도 표시되도록 해야 해요.

구조 (Anatomy)

Alert 컴포넌트는 루트 Paper 컴포넌트(<div>로 렌더링)로 구성되며, 이 안에 아이콘, 메시지, 선택적인 action이 들어 있어요:

<div class="MuiPaper-root MuiAlert-root" role="alert">
  <div class="MuiAlert-icon">
    <!-- svg icon here -->
  </div>
  <div class="MuiAlert-message">This is how an Alert renders in the DOM.</div>
  <div class="MuiAlert-action">
    <!-- optional action element here -->
  </div>
</div>

Alert API

Demos

이 React 컴포넌트 사용법에 대한 예시와 자세한 내용은 컴포넌트 데모 페이지를 방문해 주세요:

Alert

Import

import Alert from '@mui/material/Alert';
// or
import { Alert } from '@mui/material';

Props

Name	Type	Default	Required	Description
action	`node`	-	No	Alert에 추가할 동작(action)입니다.
children	`node`	-	No	컴포넌트 콘텐츠입니다.
classes	`object`	-	No	컴포넌트에 적용되는 스타일을 덮어쓰거나 확장합니다.
closeText	`string`	`'Close'`	No	닫기 버튼의 aria-label 텍스트입니다.
color	`'error' \| 'info' \| 'success' \| 'warning' \| string`	-	No	컴포넌트의 색상입니다.
icon	`node`	-	No	alert의 아이콘을 덮어씁니다.
iconMapping	`{ error?: node, info?: node, success?: node, warning?: node }`	-	No	severity별 아이콘 매핑입니다.
onClose	`function(event: React.SyntheticEvent) => void`	-	No	닫기 버튼을 클릭했을 때 호출되는 콜백입니다.
role	`string`	`'alert'`	No	루트 요소에 적용되는 ARIA role입니다.
severity	`'error' \| 'info' \| 'success' \| 'warning' \| string`	`'success'`	No	alert의 심각도입니다.
slotProps	`{ action?: func \| object, closeButton?: func \| object, closeIcon?: func \| object, icon?: func \| object, message?: func \| object, root?: func \| object }`	`{}`	No	각 slot에 대한 props입니다.
slots	`{ action?: elementType, closeButton?: elementType, closeIcon?: elementType, icon?: elementType, message?: elementType, root?: elementType }`	`{}`	No	각 slot을 렌더링할 컴포넌트입니다.
sx	`Array<func \| object \| bool> \| func \| object`	-	No	시스템 오버라이드와 추가 CSS 스타일을 정의할 수 있게 해주는 시스템 prop입니다.
variant	`'filled' \| 'outlined' \| 'standard' \| string`	`'standard'`	No	컴포넌트의 변형(variant)입니다.

Note: ref는 루트 요소(HTMLDivElement)로 전달됩니다.

그 외에 제공된 다른 props는 모두 루트 요소(Paper)에 전달됩니다.

상속 (Inheritance)

위에서 명시적으로 문서화되지는 않았지만, Paper 컴포넌트의 props도 Alert에서 사용할 수 있어요.

테마 기본 props (Theme default props)

MuiAlert를 사용해 테마로 이 컴포넌트의 기본 props를 변경할 수 있어요.

Slots

Name	Default	Class	Description
root	`Paper`	`.MuiAlert-root`	루트 slot을 렌더링하는 컴포넌트입니다.
icon	`div`	`.MuiAlert-icon`	아이콘 slot을 렌더링하는 컴포넌트입니다.
message	`div`	`.MuiAlert-message`	메시지 slot을 렌더링하는 컴포넌트입니다.
action	`div`	`.MuiAlert-action`	action slot을 렌더링하는 컴포넌트입니다.
closeButton	`IconButton`	-	닫기 버튼을 렌더링하는 컴포넌트입니다.
closeIcon	`svg`	-	닫기 아이콘을 렌더링하는 컴포넌트입니다.

CSS

규칙 이름 (Rule name)

Global class	Rule name	Description
-	colorError	`color="error"`일 때 루트 요소에 적용되는 스타일입니다.
-	colorInfo	`color="info"`일 때 루트 요소에 적용되는 스타일입니다.
-	colorSuccess	`color="success"`일 때 루트 요소에 적용되는 스타일입니다.
-	colorWarning	`color="warning"`일 때 루트 요소에 적용되는 스타일입니다.
-	filled	`variant="filled"`일 때 루트 요소에 적용되는 스타일입니다.
-	outlined	`variant="outlined"`일 때 루트 요소에 적용되는 스타일입니다.
-	standard	`variant="standard"`일 때 루트 요소에 적용되는 스타일입니다.

소스 코드 (Source code)

이 페이지에서 정보를 찾지 못했다면 컴포넌트 구현을 살펴보는 것도 방법이에요.

/packages/mui-material/src/Alert/Alert.js

AlertTitle API