Updated May 2026Edit this page ↗

Notifications

@termuijs/ui provides a NotificationCenter widget and useNotifications hook for in-app notifications. Notifications appear as auto-dismissing overlays and don't interrupt the user's current interaction.

Setup

Mount NotificationCenter once at the app root. It renders notifications as a floating overlay in the top-right corner:

○TYPESCRIPT
import { NotificationCenter } from '@termuijs/ui'
 
function App() {
    return (
        <col>
            <Dashboard />
            <NotificationCenter />
        </col>
    )
}

Sending notifications

Use useNotifications from any component in the tree:

○TYPESCRIPT
import { useNotifications } from '@termuijs/ui'
 
function SaveButton() {
    const { notify } = useNotifications()
 
    function handleSave() {
        try {
            saveData()
            notify('Saved successfully', { type: 'success' })
        } catch (err) {
            notify(`Save failed: ${err.message}`, { type: 'error', duration: 0 })
        }
    }
 
    useKeymap({ 's': handleSave })
 
    return <Text>Press s to save</Text>
}

notify(message, options?)

ParameterTypeDefaultDescription
messagestringRequiredText to display
type'info' \| 'success' \| 'warning' \| 'error''info'Sets the icon and border color
durationnumber3000Milliseconds before auto-dismiss. Pass 0 for persistent.

Returns a string ID you can use to dismiss the notification programmatically.

Notification types

TypeIcon (unicode)Icon (ASCII fallback)Border color
infoℹ[i]cyan
success✓[+]green
warning⚠[!]yellow
error✗[x]red

Icons automatically switch to ASCII fallbacks when NO_UNICODE=1.

dismiss(id)

○TYPESCRIPT
const { notify, dismiss } = useNotifications()
 
// Show a persistent notification
const id = notify('Uploading...', { type: 'info', duration: 0 })
 
// Later, when upload completes
dismiss(id)
notify('Upload complete', { type: 'success' })

Reading all active notifications

○TYPESCRIPT
const { notifications } = useNotifications()
 
// notifications: Array<{ id: string, message: string, type: string, createdAt: number }>
console.log(`${notifications.length} notifications visible`)

See also

← PreviousOverviewNext →Prompts