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"><QButtoncolor="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"><QButtoncolor="primary"onClick={() => notify({notification, placement: "top-left"})}variant="fill">Top Left</QButton><QButtoncolor="primary"onClick={() => notify({notification, placement: "top-right"})}variant="fill">Top Right</QButton><QButtoncolor="primary"onClick={() => notify({notification, placement: "bottom-left"})}variant="fill">Bottom Left</QButton><QButtoncolor="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"><QNotificationcolor="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"><QNotificationcolor="negative"description={<span className="text-primary q-font-metadata-sm">3 chipsets</span>}dismissableinlinelabel={<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"><QIconicon={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"><QIconicon={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><QButtonclassName="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 & Description | Option(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. |
| 5000 |
Replace the notification. Callback used for displaying entirely customized
notifications. When this property is supplied, the notification prop
will be ignored. |
| |
If true , the autoHideDuration timer will expire even if the window is not
focused. |
| false |
Unique identifier to reference a notification. |
| |
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 .
|
| |
Callback fired before the transition is entering. |
| |
Callback fired when the transition has entered. |
| |
Callback fired before the transition is exiting. |
| |
Callback fired when the transition has exited. |
| |
Notification stays on the screen, unless it is dismissed (programmatically or
through user interaction). |
| false |
The placement of the notification. |
| 'top-right' |
Ignores displaying multiple notifications with the same id |
| false |
The component used for the transition. |
| QSlide |
The duration for the transition, in milliseconds. |
| { enter: 225, exit: 195 } |
Properties applied to Transition component. See
TransitionProps |
| |
Props for the element that wraps the notification's Transition component. |
|
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 becausemaxNotifications
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
JSXElementConstructor<{addEndListener?: (node:| RefElement| object,done: () => void,) => voidappear?: booleanchildren?: ReactNodeclassName?: stringin?: booleanmountOnEnter?: booleannodeRef?: Ref<RefElement>onEnter?: (node:| RefElement| object,isAppearing: boolean,) => voidonEntered?: (node:| RefElement| object,isAppearing: boolean,) => voidonEntering?: (node:| RefElement| object,isAppearing: boolean,) => voidonExit?: (node:| RefElement| object,) => voidonExited?: (node:| RefElement| object,) => voidonExiting?: (node:| RefElement| object,) => voidstyle?: CSSPropertiestimeout?:| number| {appear?: numberenter?: numberexit?: number}unmountOnExit?: boolean} & {children: ReactElement}>
Default
QSlide
Description
The component used for the transition.
Type
| number| {appear?: numberenter?: numberexit?: 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 & Description | Option(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. |
| 'div' |
ReactNode | ||
The className property of the Element
interface gets and sets the value of the
class attribute
of the specified element. |
| |
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' |
The notification's description, shown just below the label. | ReactNode | |
Render a close icon that dismisses the notification when clicked. |
| |
lucide-react icon or ReactNode. If supplied, this will override the icon from
the color input. Refer to the above snippets for examples. |
| |
ID of the notification. Will be automatically assigned if not supplied. |
| |
Event fired when the dismiss button is clicked. |
| |
The style global attribute
contains CSS styling
declarations to be applied to the element. | CSSProperties |
Type
| ElementType| ComponentType
Default
'div'
Description
The component used for the root node. It can be a React component or
element.
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.
Type
ReactNode
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.
Type
CSSProperties
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 & Description | Option(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. |
| 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. |
| |
If true , the autoHideDuration timer will expire even if the window is not
focused. |
| 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. |
| |
Maximum notifications that can be stacked on top of one another. |
| 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 .
|
| |
Callback fired before the transition is entering. |
| |
Callback fired when the transition has entered. |
| |
Callback fired before the transition is exiting. |
| |
Callback fired when the transition has exited. |
| |
The placement of the notification. |
| 'top-right' |
Ignores displaying multiple notifications with the same id |
| false |
The component used for the transition. |
| QSlide |
The duration for the transition, in milliseconds. |
| { enter: 225, exit: 195 } |
Properties applied to Transition component. See
TransitionProps |
| |
Props for the element that wraps the notification's Transition component. |
|
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
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 becausemaxNotifications
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
JSXElementConstructor<{addEndListener?: (node:| RefElement| object,done: () => void,) => voidappear?: booleanchildren?: ReactNodeclassName?: stringin?: booleanmountOnEnter?: booleannodeRef?: Ref<RefElement>onEnter?: (node:| RefElement| object,isAppearing: boolean,) => voidonEntered?: (node:| RefElement| object,isAppearing: boolean,) => voidonEntering?: (node:| RefElement| object,isAppearing: boolean,) => voidonExit?: (node:| RefElement| object,) => voidonExited?: (node:| RefElement| object,) => voidonExiting?: (node:| RefElement| object,) => voidstyle?: CSSPropertiestimeout?:| number| {appear?: numberenter?: numberexit?: number}unmountOnExit?: boolean} & {children: ReactElement}>
Default
QSlide
Description
The component used for the transition.
Type
| number| {appear?: numberenter?: numberexit?: 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.