import { Canvas, ArgTypes, Meta } from '@storybook/addon-docs/blocks';

<Meta isTemplate />

# Notification

[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Notification)
&nbsp;|&nbsp;
[Usage guidelines](https://www.carbondesignsystem.com/components/notification/usage)
&nbsp;|&nbsp;
[Accessibility](https://www.carbondesignsystem.com/components/notification/accessibility)

{/* <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> */}

## Table of Contents

- [Overview](#overview)
  - [ActionableNotification](#actionablenotification)
  - [InlineNotification and ToastNotification](#inlinenotification-and-toastnotification)
  - [Callout (previously StaticNotification)](#callout-previously-staticnotification)
- [Component API](#component-api)
- [Actionable](#actionable)
  - [Using the `role` prop](#using-the-role-prop)
- [Inline](#inline)
- [Toast](#toast)
- [Feedback](#feedback)

{/* <!-- END doctoc generated TOC please keep comment here to allow auto update --> */}

## Overview

There are 4 different types of notification components:
`ActionableNotification`, `InlineNotification`, `ToastNotification`, and
`Callout`.

### ActionableNotification

`ActionableNotification` should be used when user action is required. It can
include an action, other interactive elements or rich text. It uses Toast-like
styling by default, but if you'd like it to be visually similar to an
InlineNotification, you can use the `inline` prop. If `actionButtonLabel` is not
provided, an action button will not be rendered. This component grabs and traps
focus until the action is acted upon or the notification is dismissed.

### InlineNotification and ToastNotification

`InlineNotification` and `ToastNotification` can not contain interactive
elements or rich text. These are announced by screenreaders when rendered. They
don't grab focus. Use them to provide the user with an alert, status, or log.

### Callout (previously StaticNotification)

`Callout` is non-modal and should only be used inline with content on the
initial render of the page or modal because it will not be announced to
screenreader users like the other notification components.

As such, this should not be used for real-time notifications or notifications
responding to user input (unless the page is completely refreshing and bumping
the users focus back to the first element in the dom/tab order). If a Callout is
rendered after the initial render, screenreader users' focus may have already
passed this portion of the DOM and they will not know that the notification has
been rendered until they circle back to the beginning of the page.

This is the most passive notification component and is essentially just a styled
div. If you place actions or interactive elements within this component, place
an `aria-describedby` on the interactive element with a value that matches the
`titleId` prop.

## Component API

<ArgTypes />

## Actionable

<Canvas id="components-notifications-actionable--default" />

### Using the `role` prop

ActionableNotification's `role` prop allows you to provide a different
`aria-role` than the default, `alertdialog`.

This prop should be used with caution as it will disable the focus wrapping
required for `alertdialog` . Before using this prop, consider using `Callout`
instead.

For ActionableNotification to remain accessible when using this prop, you'll be
responsible for implementing a strategy to fulfill the needs of a screenreader
user. Two viable options include:

- Rendering notifications into an existing region that can immediately be
  navigated to via a hotkey. Once the user navigates there and takes an action
  or gets to the last focusable element, focus returns from the region to the
  element previously focused before they entered the region.
- Collecting notifications in a persistent place in the app (a "drawer" or "side
  panel") and announcing to the user how they can navigate to that place to
  review all notifications and optionally take action on it.

## Inline

<Canvas id="components-notifications-inline--default" />

## Toast

<Canvas id="components-notifications-toast--default" />

## Feedback

Help us improve this component by providing feedback, asking questions on Slack,
or updating this file on
[GitHub](https://github.com/carbon-design-system/carbon/edit/main/packages/react/src/components/Notification/Notification.mdx).
