NotificationsPanel

Notification list panel with underline tabs, icon badges, pill action buttons and a customizable header and footer.

iOSAndroid

Preview NotificationsPanel on your device

Scan with Expo Go

Download Expo Go, then scan the QR code to preview native components.

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-notifications-panel

Required Packages(2 packages)

pnpm add react-native-svg tailwind-variants

Usage

import { NotificationsPanel } from '@/components/docyrus-native/notifications-panel';
import type { NotificationItem } from '@/components/docyrus-native/notifications-panel';

const notifications: NotificationItem[] = [
  {
    id: '1',
    type: 'comment',
    icon: 'fal comment',          // DocyrusIcon string, a node, or short text / emoji
    badge: 3,                     // overlay on the icon circle
    title: 'New comment on your post',
    subtitle: 'John left a comment',
    timestamp: '2m ago',
  },
  {
    id: '2',
    type: 'approval',
    variant: 'unread',
    title: 'Approval requested',
    content: <Text>Please review the <Text className="font-semibold">Q4 budget</Text>.</Text>,
    showUnreadIndicator: true,
    actions: [
      { label: 'Approve', variant: 'primary', icon: 'fal check' },
      { label: 'Reject', variant: 'danger' },
      { label: 'Open', variant: 'link' },
    ],
  },
];

<NotificationsPanel
  notifications={notifications}
  onNotificationAction={(id, action) => console.log(id, action)}
/>

With Tabs

<NotificationsPanel
  tabs={[
    { label: 'All', count: 12, active: tab === 'all', onPress: () => setTab('all') },
    { label: 'Unread', count: 3, active: tab === 'unread', onPress: () => setTab('unread') },
  ]}
  notifications={notifications}
/>

Elevated, full width

<NotificationsPanel variant="elevated" size="full" notifications={notifications} />

Copy comes from useUiTranslation() — ui.notificationsPanel.title ("Notifications") and ui.notificationsPanel.empty ("No notifications") — so an app <UiTranslationProvider> localizes it. An explicit title prop wins.

API Reference

NotificationsPanelProps

Prop	Type	Default	Description
`title`	`string`	`t('ui.notificationsPanel.title', 'Notifications')`	Header title text.
`showTitle`	`boolean`	`true`	Render the header title (native extra).
`headerAction`	`ReactNode`	—	Element rendered in the header beside the title (e.g. "Mark all as read").
`tabs`	`NotificationTab[]`	—	Underline-style filter tabs (horizontally scrollable).
`notifications`	`NotificationItem[]`	—	Notification items. Empty → `t('ui.notificationsPanel.empty', 'No notifications')`.
`notificationsMaxHeight`	`number`	—	Max height of the scrollable list (native extra).
`footer`	`ReactNode`	—	Element rendered in the muted footer bar.
`onNotificationAction`	`(notificationId: string, action: string) => void`	—	Fired after an action's own `onClick`, with the action `label`.
`variant`	`'default' \| 'elevated' \| 'bordered'`	`'default'`	`elevated` adds a large shadow (web parity); `bordered` a medium shadow (native extra).
`size`	`'sm' \| 'default' \| 'lg' \| 'full'`	`'default'`	Max width (`sm` 384, `default` 448, `lg` 512, `full` none — matters on tablets) plus header / icon density.
`className`	`string`	—	Additional classes for the panel root.

NotificationItem

Property	Type	Default	Description
`id`	`string`	—	Unique identifier.
`type`	`NotificationType`	—	Colours the icon circle and badge (`info` blue, `success` green, `warning` amber, `error` red, `comment` purple, `approval` teal, `status` slate).
`variant`	`'default' \| 'unread' \| 'highlighted'`	`'default'`	Row background.
`icon`	`ReactNode`	first letter of `type`	Icon inside the circle. A `"<lib> <name>"` string renders a white `DocyrusIcon`; other strings render as text (initials / emoji); nodes render as-is.
`badge`	`ReactNode`	—	Small overlay at the bottom-right of the icon circle (count, emoji, DocyrusIcon string or node).
`title`	`string \| ReactNode`	—	Primary text (strings are clamped to 2 lines).
`subtitle`	`string \| ReactNode`	—	Secondary text.
`content`	`ReactNode`	—	Additional content.
`timestamp`	`string`	—	Right-aligned timestamp label.
`showUnreadIndicator`	`boolean`	—	Shows an orange dot.
`actions`	`NotificationAction[]`	—	Pill action buttons under the content.

NotificationAction

Property	Type	Default	Description
`label`	`string`	—	Button label (also passed to `onNotificationAction`).
`variant`	`'default' \| 'primary' \| 'danger' \| 'link'`	`'default'`	`default` is a muted pill, `primary` / `danger` are solid, `link` is an underlined text button.
`icon`	`ReactNode`	—	Leading icon — a node or a DocyrusIcon string (`'fal check'`) tinted to the variant's text colour.
`onClick`	`() => void`	—	Called when the button is pressed.

NotificationTab

Property	Type	Default	Description
`label`	`string`	—	Tab label.
`count`	`number`	—	Shown as `(n)` after the label.
`active`	`boolean`	—	Active tab — foreground text with a 2px foreground underline.
`onPress`	`() => void`	—	Press handler.
`onClick`	`() => void`	—	Web-parity alias of `onPress` (used when `onPress` is absent).

Components

Component / export	Description
`NotificationsPanel`	The panel.
`NotificationActionButton`	The pill action button (reused by `NotificationStackCard`).
`notificationsPanelVariants`, `notificationItemVariants`, `notificationIconVariants`, `notificationBadgeVariants`, `notificationTabVariants`, `notificationButtonVariants`	`tv()` equivalents of the web CVA exports (the tab and button ones are slot-based: `base` / `label` / `count`).
`renderNotificationText`, `renderNotificationIcon`	Helpers that render the `ReactNode` / icon-string slots the RN way (strings wrapped in `<Text>`).

Type Exports

Type	Description
`NotificationsPanelProps`	Props for `NotificationsPanel`.
`NotificationItem`	Notification item data shape (shared with `NotificationStack`).
`NotificationType`	`'comment' \| 'approval' \| 'status' \| 'info' \| 'success' \| 'warning' \| 'error'`.
`NotificationItemVariant`	`'default' \| 'unread' \| 'highlighted'`.
`NotificationAction`	Action button definition.
`NotificationActionVariant`	`'default' \| 'primary' \| 'danger' \| 'link'`.
`NotificationTab`	Tab definition.
`NotificationsPanelSize`	`'sm' \| 'default' \| 'lg' \| 'full'`.
`NotificationsPanelVariant`	`'default' \| 'elevated' \| 'bordered'`.

Breaking changes

Embedded en / tr copy removed. The title and empty text now come from useUiTranslation() (ui.notificationsPanel.title, ui.notificationsPanel.empty) with English fallbacks. The previous Turkish fallback and the DocyThemeProvider.messages['notifications-panel.*'] lookup no longer apply — provide the keys through <UiTranslationProvider>.
size now also sets a max width (sm 384 / default 448 / lg 512 px, web parity); pass size="full" for the old edge-to-edge width on tablets. Row text no longer scales with size (only the header title and icon circle do).
Restyle (web June restyle): icon circles are solid type colours with a white icon, tabs use a foreground underline instead of the primary one, action buttons are muted / solid pills instead of outlined chips, and danger actions are solid destructive buttons.
bordered keeps its medium shadow; the new elevated variant adds a large one.

NotificationsPanel

On this page