QUI React

Notifications

A notification is an interactive message that is delivered within the context of an application. It serves to inform, update, or engage users by providing timely and relevant information, alerts, or calls to action.

import {useNotification} from "@qui/react"

Examples

Context

The recommended approach for rendering notifications is through the useNotification hook. Before starting with this approach, ensure that you've finished the setup guide.

import {ReactNode} from "react"
import {DownloadCloud} from "lucide-react"
import {QButton, useNotification} from "@qui/react"
export default function Context(): ReactNode {
const {notify} = useNotification()
return (
<div className="grid justify-center">
<QButton
color="primary"
onClick={() => {
notify({
notification: {
color: "informative",
icon: DownloadCloud,
label: (
<span>
<span>Snapdragon Spaces SDK</span>
<span className="q-body-s subtle"> downloading</span>
</span>
),
},
})
}}
variant="fill"
>
Notify
</QButton>
</div>
)
}

Placement

Customize the anchor origin of the notification using the placement property of the notify function.

import {ReactNode} from "react"
import {DownloadCloud} from "lucide-react"
import {QButton, QNotificationProps, useNotification} from "@qui/react"
const notification: QNotificationProps = {
color: "informative",
description: "Description",
icon: DownloadCloud,
label: "Label",
}
export default function Placement(): ReactNode {
const {notify} = useNotification()
return (
<div className="grid justify-center">
<div className="grid grid-cols-2 grid-rows-2 gap-4">
<QButton
color="primary"
onClick={() => notify({notification, placement: "top-left"})}
variant="fill"
>
Top Left
</QButton>
<QButton
color="primary"
onClick={() => notify({notification, placement: "top-right"})}
variant="fill"
>
Top Right
</QButton>
<QButton
color="primary"
onClick={() => notify({notification, placement: "bottom-left"})}
variant="fill"
>
Bottom Left
</QButton>
<QButton
color="primary"
onClick={() => notify({notification, placement: "bottom-right"})}
variant="fill"
>
Bottom Right
</QButton>
</div>
</div>
)
}

Declarative

The notification can also be used inline.

Snapdragon Spaces SDK installation complete
import {ReactNode} from "react"
import {QNotification} from "@qui/react"
export default function Inline(): ReactNode {
return (
<div className="grid justify-center">
<QNotification
color="positive"
label={
<span>
Snapdragon Spaces SDK{" "}
<span className="q-body-s">installation complete</span>
</span>
}
/>
</div>
)
}

Customization

Customize the notification's look and feel with ReactNode props.

ProtonMail_v2.3 Job Failed
910.7%
7589.3%
import {ReactNode} from "react"
import {AlertTriangle, Check, ChevronRight} from "lucide-react"
import {QButton, QIcon, QNotification} from "@qui/react"
export default function Customization(): ReactNode {
return (
<div className="grid justify-center">
<QNotification
color="negative"
description={
<span className="text-primary q-font-metadata-sm">3 chipsets</span>
}
dismissable
inline
label={
<span className="text-primary q-font-heading-xs">
ProtonMail_v2.3 Job Failed
</span>
}
>
<div className="grid justify-start gap-2">
<div className="flex gap-4">
<div className="flex items-center gap-1">
<QIcon
icon={AlertTriangle}
style={{color: "var(--q-notification-negative)"}}
/>
<div className="flex items-baseline gap-1">
<span className="q-body-s q-text-1-primary">9</span>
<span className="q-body-xs q-text-1-secondary">10.7%</span>
</div>
</div>
<div className="flex items-center gap-1">
<QIcon
icon={Check}
style={{color: "var(--q-notification-positive)"}}
/>
<div className="flex items-baseline gap-1">
<span className="q-body-s q-text-1-primary">75</span>
<span className="q-body-xs q-text-1-secondary">89.3%</span>
</div>
</div>
</div>
<QButton
className="justify-self-start"
endIcon={<QIcon icon={ChevronRight} />}
size="s"
variant="outline"
>
Job Details
</QButton>
</div>
</QNotification>
</div>
)
}

API

Notify

The notify function is returned from the useNotification hook.

type Notify = (options: QNotifyOptions) => string
const {notify} = useNotification()

QNotifyOptions

Name & DescriptionOption(s)Default
The number of milliseconds to wait before automatically calling the onClose function. By default, notifications get closed after 5000 milliseconds. Set autoHideDuration to 'null' if you don't want notifications to automatically close. Alternatively pass persist: true in the options parameter of notify.
number
5000
Replace the notification. Callback used for displaying entirely customized notifications. When this property is supplied, the notification prop will be ignored.
| ReactNode
| ((
id: string,
) => ReactNode)
If true, the autoHideDuration timer will expire even if the window is not focused.
boolean
false
Unique identifier to reference a notification.
| string
| number
The notification to render.
QNotificationProps
Callback fired before the notification is closed. The reason parameter can optionally be used to control the response to onClose.
  • eventThe event source of the callback
  • reason
    -
    timeout autoHideDuration expired.
    -
    max-notifications notification was closed because maxNotifications has reached.
    -
    instructed notification was closed programmatically.
  • idid of a notification. id will be undefined if close is called with no key (user requested all the notifications to be closed)
(
event: SyntheticEvent,
reason:
| 'timeout'
| 'max-notifications'
| 'instructed',
id?: string,
) => void
Callback fired before the transition is entering.
    (
    node: HTMLElement,
    isAppearing: boolean,
    id: string,
    ) => void
    Callback fired when the transition has entered.
      (
      node: HTMLElement,
      isAppearing: boolean,
      id: string,
      ) => void
      Callback fired before the transition is exiting.
        (
        node: HTMLElement,
        id: string,
        ) => void
        Callback fired when the transition has exited.
          (
          node: HTMLElement,
          id: string,
          ) => void
          Notification stays on the screen, unless it is dismissed (programmatically or through user interaction).
          boolean
          false
          
          The placement of the notification.
          | 'top-left'
          | 'top-right'
          | 'bottom-left'
          | 'bottom-right'
          'top-right'
          
          Ignores displaying multiple notifications with the same id
          boolean
          false
          
          The component used for the transition.
          JSXElementConstructor<
          {
          addEndListener?: (
          node:
          | RefElement
          | object,
          done: () => void,
          ) => void
          appear?: boolean
          children?: ReactNode
          className?: string
          in?: boolean
          mountOnEnter?: boolean
          nodeRef?: Ref<RefElement>
          onEnter?: (
          node:
          | RefElement
          | object,
          isAppearing: boolean,
          ) => void
          onEntered?: (
          node:
          | RefElement
          | object,
          isAppearing: boolean,
          ) => void
          onEntering?: (
          node:
          | RefElement
          | object,
          isAppearing: boolean,
          ) => void
          onExit?: (
          node:
          | RefElement
          | object,
          ) => void
          onExited?: (
          node:
          | RefElement
          | object,
          ) => void
          onExiting?: (
          node:
          | RefElement
          | object,
          ) => void
          style?: CSSProperties
          timeout?:
          | number
          | {
          appear?: number
          enter?: number
          exit?: number
          }
          unmountOnExit?: boolean
          } & {
          children: ReactElement
          }
          >
          QSlide
          The duration for the transition, in milliseconds.
          | number
          | {
          appear?: number
          enter?: number
          exit?: number
          }
          { enter: 225, exit: 195 }
          
          Properties applied to Transition component. See TransitionProps
          Partial<TransitionProps>
          Props for the element that wraps the notification's Transition component.
          HTMLAttributes<HTMLDivElement>
          Type
          number
          Default
          5000
          
          Description
          The number of milliseconds to wait before automatically calling the onClose function. By default, notifications get closed after 5000 milliseconds. Set autoHideDuration to 'null' if you don't want notifications to automatically close. Alternatively pass persist: true in the options parameter of notify.
          Type
          | ReactNode
          | ((
          id: string,
          ) => ReactNode)
          Description
          Replace the notification. Callback used for displaying entirely customized notifications. When this property is supplied, the notification prop will be ignored.
          Type
          boolean
          Default
          false
          
          Description
          If true, the autoHideDuration timer will expire even if the window is not focused.
          Type
          | string
          | number
          Description
          Unique identifier to reference a notification.
          Description
          The notification to render.
          Type
          (
          event: SyntheticEvent,
          reason:
          | 'timeout'
          | 'max-notifications'
          | 'instructed',
          id?: string,
          ) => void
          Description
          Callback fired before the notification is closed. The reason parameter can optionally be used to control the response to onClose.
          • eventThe event source of the callback
          • reason
            -
            timeout autoHideDuration expired.
            -
            max-notifications notification was closed because maxNotifications has reached.
            -
            instructed notification was closed programmatically.
          • idid of a notification. id will be undefined if close is called with no key (user requested all the notifications to be closed)
          Type
          (
          node: HTMLElement,
          isAppearing: boolean,
          id: string,
          ) => void
          Description
          Callback fired before the transition is entering.
            Type
            (
            node: HTMLElement,
            isAppearing: boolean,
            id: string,
            ) => void
            Description
            Callback fired when the transition has entered.
              Type
              (
              node: HTMLElement,
              id: string,
              ) => void
              Description
              Callback fired before the transition is exiting.
                Type
                (
                node: HTMLElement,
                id: string,
                ) => void
                Description
                Callback fired when the transition has exited.
                  Type
                  boolean
                  Default
                  false
                  
                  Description
                  Notification stays on the screen, unless it is dismissed (programmatically or through user interaction).
                  Type
                  | 'top-left'
                  | 'top-right'
                  | 'bottom-left'
                  | 'bottom-right'
                  Default
                  'top-right'
                  
                  Description
                  The placement of the notification.
                  Type
                  boolean
                  Default
                  false
                  
                  Description
                  Ignores displaying multiple notifications with the same id
                  Type
                  JSXElementConstructor<
                  {
                  addEndListener?: (
                  node:
                  | RefElement
                  | object,
                  done: () => void,
                  ) => void
                  appear?: boolean
                  children?: ReactNode
                  className?: string
                  in?: boolean
                  mountOnEnter?: boolean
                  nodeRef?: Ref<RefElement>
                  onEnter?: (
                  node:
                  | RefElement
                  | object,
                  isAppearing: boolean,
                  ) => void
                  onEntered?: (
                  node:
                  | RefElement
                  | object,
                  isAppearing: boolean,
                  ) => void
                  onEntering?: (
                  node:
                  | RefElement
                  | object,
                  isAppearing: boolean,
                  ) => void
                  onExit?: (
                  node:
                  | RefElement
                  | object,
                  ) => void
                  onExited?: (
                  node:
                  | RefElement
                  | object,
                  ) => void
                  onExiting?: (
                  node:
                  | RefElement
                  | object,
                  ) => void
                  style?: CSSProperties
                  timeout?:
                  | number
                  | {
                  appear?: number
                  enter?: number
                  exit?: number
                  }
                  unmountOnExit?: boolean
                  } & {
                  children: ReactElement
                  }
                  >
                  Default
                  QSlide
                  Description
                  The component used for the transition.
                  Type
                  | number
                  | {
                  appear?: number
                  enter?: number
                  exit?: number
                  }
                  Default
                  { enter: 225, exit: 195 }
                  
                  Description
                  The duration for the transition, in milliseconds.
                  Type
                  Partial<TransitionProps>
                  Description
                  Properties applied to Transition component. See TransitionProps
                  Type
                  HTMLAttributes<HTMLDivElement>
                  Description
                  Props for the element that wraps the notification's Transition component.

                  QNotificationProps

                  These props apply to the QNotification component when it is used inline:

                  // example
                  <QNotification label="Label" />
                  Name & DescriptionOption(s)Default
                  Label text – the notification's primary message.
                  ReactNode
                  The component used for the root node. It can be a React component or element.
                  | ElementType
                  | ComponentType
                  'div'
                  
                  React children prop.
                  ReactNode
                  The className property of the Element interface gets and sets the value of the class attribute of the specified element.
                  string
                  The color of the notification. Used to control the rendered icon and its background-color. The icon can be overridden using the icon input.
                  | 'informative'
                  | 'positive'
                  | 'warning'
                  | 'negative'
                  'informative'
                  
                  The notification's description, shown just below the label.
                  ReactNode
                  Render a close icon that dismisses the notification when clicked.
                  boolean
                  lucide-react icon or ReactNode. If supplied, this will override the icon from the color input. Refer to the above snippets for examples.
                  | LucideIcon
                  | ReactNode
                  ID of the notification. Will be automatically assigned if not supplied.
                  string
                  Event fired when the dismiss button is clicked.
                      (
                      event: SyntheticEvent,
                      ) => void
                      The style global attribute contains CSS styling declarations to be applied to the element.
                      CSSProperties
                      Description
                      Label text – the notification's primary message.
                      Type
                      | ElementType
                      | ComponentType
                      Default
                      'div'
                      
                      Description
                      The component used for the root node. It can be a React component or element.
                      Description
                      React children prop.
                      Type
                      string
                      Description
                      The className property of the Element interface gets and sets the value of the class attribute of the specified element.
                      Type
                      | 'informative'
                      | 'positive'
                      | 'warning'
                      | 'negative'
                      Default
                      'informative'
                      
                      Description
                      The color of the notification. Used to control the rendered icon and its background-color. The icon can be overridden using the icon input.
                      Description
                      The notification's description, shown just below the label.
                      Type
                      boolean
                      Description
                      Render a close icon that dismisses the notification when clicked.
                      Type
                      | LucideIcon
                      | ReactNode
                      Description
                      lucide-react icon or ReactNode. If supplied, this will override the icon from the color input. Refer to the above snippets for examples.
                      Type
                      string
                      Description
                      ID of the notification. Will be automatically assigned if not supplied.
                      Type
                      (
                      event: SyntheticEvent,
                      ) => void
                      Description
                      Event fired when the dismiss button is clicked.
                          Description
                          The style global attribute contains CSS styling declarations to be applied to the element.

                          QNotificationProviderProps

                          Your app should already be wrapped in the QuiRoot component. If not, please head to the Installation page and finish the setup guide.

                          Many of the Notification options available in the hook are also available on the provider. You can supply these props to the QuiRoot component's notificationProviderProps prop to configure app-wide settings for your notifications.

                          You may optionally wrap sections of your app with a QNotificationProvider to configure separate instances of context for your notifications. Each provider maintains its own configuration and state, which may result in overlapping notifications. You should pick different screen placements for each provider if you choose this approach.

                          Name & DescriptionOption(s)Default
                          The number of milliseconds to wait before automatically calling the onClose function. By default, notifications get closed after 5000 milliseconds. Set autoHideDuration to 'null' if you don't want notifications to automatically close. Alternatively pass persist: true in the options parameter of notify.
                          number
                          5000
                          
                          Most of the time this is your App. every component from this point onward will be able to show notifications.
                          ReactNode
                          Replace the notification. Callback used for displaying entirely customized notifications. When this property is supplied, the notification prop will be ignored.
                          | ReactNode
                          | ((
                          id: string,
                          ) => ReactNode)
                          If true, the autoHideDuration timer will expire even if the window is not focused.
                          boolean
                          false
                          
                          Valid HTML Node element, used to target ReactDOM.createPortal. If you are using this prop, most likely you also want to apply position: absolute to QNotificationContainer.
                          HTMLElement
                          Maximum notifications that can be stacked on top of one another.
                          number
                          3
                          
                          The notification to render.
                          QNotificationProps
                          Callback fired before the notification is closed. The reason parameter can optionally be used to control the response to onClose.
                          • eventThe event source of the callback
                          • reason
                            -
                            timeout autoHideDuration expired.
                            -
                            max-notifications notification was closed because maxNotifications has reached.
                            -
                            instructed notification was closed programmatically.
                          • idid of a notification. id will be undefined if close is called with no key (user requested all the notifications to be closed)
                          (
                          event: SyntheticEvent,
                          reason:
                          | 'timeout'
                          | 'max-notifications'
                          | 'instructed',
                          id?: string,
                          ) => void
                          Callback fired before the transition is entering.
                            (
                            node: HTMLElement,
                            isAppearing: boolean,
                            id: string,
                            ) => void
                            Callback fired when the transition has entered.
                              (
                              node: HTMLElement,
                              isAppearing: boolean,
                              id: string,
                              ) => void
                              Callback fired before the transition is exiting.
                                (
                                node: HTMLElement,
                                id: string,
                                ) => void
                                Callback fired when the transition has exited.
                                  (
                                  node: HTMLElement,
                                  id: string,
                                  ) => void
                                  The placement of the notification.
                                  | 'top-left'
                                  | 'top-right'
                                  | 'bottom-left'
                                  | 'bottom-right'
                                  'top-right'
                                  
                                  Ignores displaying multiple notifications with the same id
                                  boolean
                                  false
                                  
                                  The component used for the transition.
                                  JSXElementConstructor<
                                  {
                                  addEndListener?: (
                                  node:
                                  | RefElement
                                  | object,
                                  done: () => void,
                                  ) => void
                                  appear?: boolean
                                  children?: ReactNode
                                  className?: string
                                  in?: boolean
                                  mountOnEnter?: boolean
                                  nodeRef?: Ref<RefElement>
                                  onEnter?: (
                                  node:
                                  | RefElement
                                  | object,
                                  isAppearing: boolean,
                                  ) => void
                                  onEntered?: (
                                  node:
                                  | RefElement
                                  | object,
                                  isAppearing: boolean,
                                  ) => void
                                  onEntering?: (
                                  node:
                                  | RefElement
                                  | object,
                                  isAppearing: boolean,
                                  ) => void
                                  onExit?: (
                                  node:
                                  | RefElement
                                  | object,
                                  ) => void
                                  onExited?: (
                                  node:
                                  | RefElement
                                  | object,
                                  ) => void
                                  onExiting?: (
                                  node:
                                  | RefElement
                                  | object,
                                  ) => void
                                  style?: CSSProperties
                                  timeout?:
                                  | number
                                  | {
                                  appear?: number
                                  enter?: number
                                  exit?: number
                                  }
                                  unmountOnExit?: boolean
                                  } & {
                                  children: ReactElement
                                  }
                                  >
                                  QSlide
                                  The duration for the transition, in milliseconds.
                                  | number
                                  | {
                                  appear?: number
                                  enter?: number
                                  exit?: number
                                  }
                                  { enter: 225, exit: 195 }
                                  
                                  Properties applied to Transition component. See TransitionProps
                                  Partial<TransitionProps>
                                  Props for the element that wraps the notification's Transition component.
                                  HTMLAttributes<HTMLDivElement>
                                  Type
                                  number
                                  Default
                                  5000
                                  
                                  Description
                                  The number of milliseconds to wait before automatically calling the onClose function. By default, notifications get closed after 5000 milliseconds. Set autoHideDuration to 'null' if you don't want notifications to automatically close. Alternatively pass persist: true in the options parameter of notify.
                                  Description
                                  Most of the time this is your App. every component from this point onward will be able to show notifications.
                                  Type
                                  | ReactNode
                                  | ((
                                  id: string,
                                  ) => ReactNode)
                                  Description
                                  Replace the notification. Callback used for displaying entirely customized notifications. When this property is supplied, the notification prop will be ignored.
                                  Type
                                  boolean
                                  Default
                                  false
                                  
                                  Description
                                  If true, the autoHideDuration timer will expire even if the window is not focused.
                                  Type
                                  HTMLElement
                                  Description
                                  Valid HTML Node element, used to target ReactDOM.createPortal. If you are using this prop, most likely you also want to apply position: absolute to QNotificationContainer.
                                  Type
                                  number
                                  Default
                                  3
                                  
                                  Description
                                  Maximum notifications that can be stacked on top of one another.
                                  Description
                                  The notification to render.
                                  Type
                                  (
                                  event: SyntheticEvent,
                                  reason:
                                  | 'timeout'
                                  | 'max-notifications'
                                  | 'instructed',
                                  id?: string,
                                  ) => void
                                  Description
                                  Callback fired before the notification is closed. The reason parameter can optionally be used to control the response to onClose.
                                  • eventThe event source of the callback
                                  • reason
                                    -
                                    timeout autoHideDuration expired.
                                    -
                                    max-notifications notification was closed because maxNotifications has reached.
                                    -
                                    instructed notification was closed programmatically.
                                  • idid of a notification. id will be undefined if close is called with no key (user requested all the notifications to be closed)
                                  Type
                                  (
                                  node: HTMLElement,
                                  isAppearing: boolean,
                                  id: string,
                                  ) => void
                                  Description
                                  Callback fired before the transition is entering.
                                    Type
                                    (
                                    node: HTMLElement,
                                    isAppearing: boolean,
                                    id: string,
                                    ) => void
                                    Description
                                    Callback fired when the transition has entered.
                                      Type
                                      (
                                      node: HTMLElement,
                                      id: string,
                                      ) => void
                                      Description
                                      Callback fired before the transition is exiting.
                                        Type
                                        (
                                        node: HTMLElement,
                                        id: string,
                                        ) => void
                                        Description
                                        Callback fired when the transition has exited.
                                          Type
                                          | 'top-left'
                                          | 'top-right'
                                          | 'bottom-left'
                                          | 'bottom-right'
                                          Default
                                          'top-right'
                                          
                                          Description
                                          The placement of the notification.
                                          Type
                                          boolean
                                          Default
                                          false
                                          
                                          Description
                                          Ignores displaying multiple notifications with the same id
                                          Type
                                          JSXElementConstructor<
                                          {
                                          addEndListener?: (
                                          node:
                                          | RefElement
                                          | object,
                                          done: () => void,
                                          ) => void
                                          appear?: boolean
                                          children?: ReactNode
                                          className?: string
                                          in?: boolean
                                          mountOnEnter?: boolean
                                          nodeRef?: Ref<RefElement>
                                          onEnter?: (
                                          node:
                                          | RefElement
                                          | object,
                                          isAppearing: boolean,
                                          ) => void
                                          onEntered?: (
                                          node:
                                          | RefElement
                                          | object,
                                          isAppearing: boolean,
                                          ) => void
                                          onEntering?: (
                                          node:
                                          | RefElement
                                          | object,
                                          isAppearing: boolean,
                                          ) => void
                                          onExit?: (
                                          node:
                                          | RefElement
                                          | object,
                                          ) => void
                                          onExited?: (
                                          node:
                                          | RefElement
                                          | object,
                                          ) => void
                                          onExiting?: (
                                          node:
                                          | RefElement
                                          | object,
                                          ) => void
                                          style?: CSSProperties
                                          timeout?:
                                          | number
                                          | {
                                          appear?: number
                                          enter?: number
                                          exit?: number
                                          }
                                          unmountOnExit?: boolean
                                          } & {
                                          children: ReactElement
                                          }
                                          >
                                          Default
                                          QSlide
                                          Description
                                          The component used for the transition.
                                          Type
                                          | number
                                          | {
                                          appear?: number
                                          enter?: number
                                          exit?: number
                                          }
                                          Default
                                          { enter: 225, exit: 195 }
                                          
                                          Description
                                          The duration for the transition, in milliseconds.
                                          Type
                                          Partial<TransitionProps>
                                          Description
                                          Properties applied to Transition component. See TransitionProps
                                          Type
                                          HTMLAttributes<HTMLDivElement>
                                          Description
                                          Props for the element that wraps the notification's Transition component.