Notifications

The Notification component is used to display notifications in your application.

import { NotificationCenter, toaster } from '@cerberus/react'

Usage

The NotificationCenter component is used to manage notifications in your application. It works together with the toaster object to display notifications.

'use client';

import { toaster } from '@cerberus/react'

function Feature() {
const handleClick = useCallback(() => {
toaster.create({
type: 'info',
title: 'Update Available',
description: 'A new version of the app is available',
action: {
label: 'Refresh',
onClick: () => {
window.location.reload()
}
}
})
}, [])

return <Button onClick={handleClick}>Trigger notification</Button>
}

import { NotificationCenter } from '@cerberus/react'

export function Layout(props: PropsWithChildren<{}>) {
  return (
    <>
      {props.children}
      <NotificationCenter />
    </>
  )
}

Types

Just update the options.types to change the theme of the notification. The options are info, success, warning, danger, and loading.

'use client';

import { toaster } from '@cerberus/react'

function Feature() {
const handleClick = useCallback(() => {
toaster.create({
type: 'loading',
title: 'Loading',
description: 'It's taking longer than normal.',
})
}, [toaster.create])

return <Button onClick={handleClick}>Trigger notification</Button>
}

Subtle Notifications

Subtle notifications are a less intrusive way to inform users about events or updates. They typically have a softer appearance and may not require immediate user action.

Use the usage: 'subtle' option to create a subtle notification.

'use client';

import { toaster } from '@cerberus/react'

function Feature() {
  const handleClick = useCallback(() => {
    toaster.create({
      type: 'info',
      usage: 'subtle',
      title: 'Update Available',
      description: 'A new version of the app is available',
      action: {
        label: 'Refresh',
        onClick: () => {
          window.location.reload()
        }
      }
    })
  }, [])

  return <Button onClick={handleClick}>Trigger subtle notification</Button>
}

Custom Configuration

You can customize the notification behavior by calling the createToaster function. This allows you to create a new toaster instance with your desired configuration.

We recommend scoping this to a component to ensure Next.js rehydration works correctly.

'use client';

import { createToaster, NotificationCenter, Button } from '@cerberus/react'
import { HStack } from 'styled-system/jsx'

function CustomConfigDemo() {
const customToaster = createToaster({
gap: 24,
overlap: false,
placement: 'bottom-end',
})

return (

<>
<HStack>
<Button
onClick={() => {
customToaster.create({
title: 'Custom Toaster',
description:
'This notification is using a custom toaster configuration.',
type: 'success',
})
}} >
Show Notification
</Button>
</HStack>

      <NotificationCenter toaster={customToaster} />
    </>

)
}

Badges

Badges can be used to show the number of notifications on any trigger by using the data-notify and data-notify-count attributes.

Note

Combine this with the `formatNotifyCount` helper that will restrict the count to 3 digits.

import { IconButton, formatNotifyCount } from '@cerberus/react'
import { Notifications } from '@cerberus/icons'

export function NotifyBadgePreview() {
  return (
    <IconButton
      ariaLabel="View notifications"
      data-notify
      data-notify-count={formatNotifyCount(100)}
    >
    <Notifications />
  </IconButton>
  )
}

Primitives

You can utilize the primitive components to customize the toast notification.

Component	Description
NotificationProvider	The context provider for the toast notifications.
NotificationRoot	The context provider for the toast parts.
NotificationHeading	The title heading of the toast.
NotificationDescription	The description of the toast.
NotificationCloseTrigger	The close button of the toast.
NotificationActionTrigger	The action button of the toast.

API

Props

The NotificationCenter component is an abstraction of the primitives and doesn't accept any props.

`toaster`

The toaster object is used to create notifications and accepts the following options:

Name	Type	Description
type	string	The type of notification. Options are `info`, `success`, `warning`, `error`, and `loading`.
title	string	The title of the notification.
description	string	The description of the notification.
action	`ToasterAction`	The action object of the notification.
duration	number	A custom duration of the notification.
onClose	function	The callback function when the notification is closed.
usage	`'subtle' \| 'default'`	The visual type of the notification. The default option is `default`.

`ToasterAction`

The ToasterAction object is used to create an action button for the notification and accepts the following options:

Name	Type	Description
label	string	The label of the action button.
onClick	function	The callback function when the action button is clicked.

Parts

The NotificationParts API is an Object containing the full family of components.

Note

It is best to only use the NotificationParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

Name	Description
Root	The `NotificationRoot` component which is the Provider for the toast.
Heading	The `NotificationHeading` component which displays the heading title for the toast.
Description	The `NotificationDescription` component which displays the description for the toast.
CloseTrigger	The `NotificationCloseTrigger` component which displays the close button for the toast.
ActionTrigger	The `NotificationActionTrigger` component which displays the action button for the toast.

On this page