---
name: Notification
menu: Components
---

import PropsTable from 'website-src/components/PropsTable'
import Notification from './Notification'
import Alert from '../Alert/Alert'
import Button from '../Button/Button'
import ScreenSizeProvider from '../ScreenSizeProvider/ScreenSizeProvider'
import { livePreviewStyle } from '../helpers/constants'
import { LiveProvider, LiveEditor, LiveError, LivePreview } from 'react-live'

# Notification

A component that overlays its children on the screen in different positions to help with rendering notifications like alerts.

## Basic usage

The `Notification` component has three props:
  - `open`: Tells the component whether or not to display its children.
  - `vertical`: Tells the component where to render the children vertically. Valid options are "top" or "bottom". Defaults to "bottom".
  - `horizontal`: Tells the component where to render the children horizontally. Valid options are "left", "center", or "right". Defaults
  to "center" for tiny screens and "right" for any screens larger than that.

This component calls the `useScreenSize` hook internally, so it should always be rendered as a descendant of `ScreenSizeProvider`.

### Try It Out

export const code = `
const NotificationContainer = () => {
  const [open, setOpen] = React.useState(false)
  return (
    <>
      <Button onClick={() => setOpen(true)}>
        Open Notification
      </Button>
      <Notification open={open} vertical="bottom" horizontal="right">
        <Alert status="error" onClose={() => setOpen(false)}>I am an overlayed alert!</Alert>
      </Notification>
    </>
  )
}
render(<ScreenSizeProvider><NotificationContainer /></ScreenSizeProvider>)
`

<LiveProvider code={code} scope={{ Notification, Alert, Button, ScreenSizeProvider }} noInline={true}>
  <LiveEditor style={livePreviewStyle} />
  <LiveError />
  <LivePreview />
</LiveProvider>

## NotificationProvider

To make it possible to set notifications at any level without overlapping,
we provide a `NotificationProvider` component along with a `useNotifications` hook.
Simply wrap your app in the provider, which takes no props but children,
and the hook gives two functions to manage notifications:

```ts
function useNotifications(): NotificationController;
interface NotificationController {
  setNotification: (args: AlertArgs | ElementArgs) => Key
  clearNotification: Key
}
interface NotificationProps {
  key?: string
  vertical?: 'top' | 'bottom'
  horizontal?: 'left' | 'center' | 'right'
}
interface AlertArgs extends AlertProps, NotificationProps {
  message: React.ReactChild
  status: AlertStatus
  canClose?: boolean
}
interface ElementArgs extends NotificationProps {
  element: React.ReactElement
}
```

The easiest way to use `setNotification` is to pass the same props you would pass
to the `Alert` component except that instead of passing the contents as children,
it has the `message` property, `status` is required, and you can pass a `canClose` argument
(default true) to automatically generate the `onClose` handler to call `clearNotification`.
You can still pass a custom `onClose` handler or a `closeTimeout` as well.

If you want to use something other than an `Alert`, you can pass a pre-built element instead.
Both argument forms also accept the `Notification` positioning props, `vertical` and `horizontal`,
and optionally a unique key to identify the note (if no key is provided, one will be generated).

### Positioning & Multiple Notifications

If multiple notifications are added with the same position, they will be combined
into a single `Notification` element, rendered in the order they were added;
given the fixed positioning of `Notification`, this prevents them from overlapping.
However, if notifications are set in different positions there is no automatic
way to keep them from overlapping, so keep that in mind if you use lots of notifications.

## Properties

<PropsTable of={Notification} />