> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

> Customize Velt notification tools and panels with props, classes, wireframes, hooks, and limitations.

The notifications bell (tool) + the notifications panel (inbox with For-you / All / Documents / People tabs + a settings view). **Fully wireframed**, with rich config props: all four layers apply.

> [!TIP]
>
> **Have this design in Figma?** The [UI Customization Plugin](https://velt.dev/docs/get-started/ui-customization-plugin.md) for Cursor and Claude Code turns a Figma design into verified Velt UI customization (comments and notifications today): it picks the approach, builds your notification tool and panel in your app, and verifies the result against the design in a real browser.

## Components

**Full examples:** the per-component pages have complete tabbed code examples and screenshots: [Notifications tool wireframes](https://velt.dev/docs/ui-customization/features/async/notifications/notifications-tool/wireframes.md), [Notifications panel wireframes](https://velt.dev/docs/ui-customization/features/async/notifications/notifications-panel/wireframes.md), and the matching [tool](https://velt.dev/docs/ui-customization/features/async/notifications/notifications-tool/primitives.md) and [panel](https://velt.dev/docs/ui-customization/features/async/notifications/notifications-panel/primitives.md) primitives pages.

| | Primitive | Wireframe |
| - | - | - |
| Bell / trigger | `VeltNotificationsTool` | `VeltNotificationsToolWireframe` |
| Inbox panel | `VeltNotificationsPanel` | `VeltNotificationsPanelWireframe` |
| History panel (inline) | `VeltNotificationsHistoryPanel` | None |

## Config props

Cheapest customization: do this first. On `VeltNotificationsTool` / `VeltNotificationsPanel`:

| Prop | Values | Notes |
| - | - | - |
| `panelOpenMode` | `'popover'` · `'sidebar'` | popover vs docked panel |
| `settingsLayout` | `'accordion'` · `'dropdown'` | settings UI |
| `tabConfig` | `{ forYou?, documents?, all?, people?: { name?, enable? } }` | enable/rename/reorder tabs |
| `settings` | `boolean` | show/hide settings view |
| `enableSettingsAtOrganizationLevel` | `boolean` | org-scoped settings |
| `enableCrossOrganization` | `boolean \| string \| CrossOrganizationConfig` | cross-org feeds (only `forYou` feed supported; current org excluded) |
| `enableUserScopedNotifications` | `boolean \| string \| UserScopedNotificationsConfig` | user-scoped "For You" fetch (default `limit` 25, clamped `[1, 200]`) |
| `considerAllNotifications` | `boolean` | **Tool-only**: count all, not just unread |
| `selfNotifications` / `readNotificationsOnForYouTab` | `boolean` | include self / auto-read on For-you |
| `pageSize` (default 5) / `maxDays` (Tool-only) | `number` (>0) | page size / history window |
| `darkMode` / `shadowDom` / `variant` | None | theme / shadow-DOM / variant; Tool also has `panelShadowDom` / `panelVariant` |

> Boolean attributes only emit when explicitly `true`/`false`; `shadowDom`/`panelShadowDom` default to `true`. `pageSize`/`maxDays` are ignored unless `> 0`.

## CSS: stateful classes

(Override with `!important` because Velt's own styles are high-specificity; see [CSS](https://velt.dev/docs/ui-customization/styling.md#override-classes).)

| Class | Applied when |
| - | - |
| `velt-notifications-tool`, `active` / `velt-notification-tool-open` | Tool; panel open |
| `velt-notifications-panel--tab`, `velt-notifications-panel--tab-selected` | Tabs; active tab |
| `velt-notifications-panel--sidebar-panel`, `bottom-sheet` | Panel mode |
| `velt-notifications-panel--list-item-unread`, `velt-notifications-panel--unread-is-default` | Unread items |
| `velt-notification-panel--settings-accordion-container-expanded` / `…-open` | Settings accordion |
| `velt-notification-panel--settings-mute-all-toggle-container-muted` | Mute-all toggle |

## Wireframes: slot trees + tokens

**`VeltNotificationsToolWireframe`:** `.Icon` · `.Label` · `.UnreadIcon` · `.UnreadCount`. (Root prop `variant`.)

**`VeltNotificationsPanelWireframe`** (abridged; full tree in [Wireframe components](https://velt.dev/docs/ui-customization/reference/wireframe-components.md)):

```
VeltNotificationsPanelWireframe
├── .Header → .TabAll / .TabForYou / .TabDocuments / .TabPeople
├── .Title  .TitleText  .ReadAllButton  .ViewAllButton  .CloseButton  .Skeleton  .SettingsButton
├── .Content
│   ├── .All     → .List → .Item → .Label / .Content
│   ├── .ForYou
│   ├── .Documents → .List → .Item → .Content / .Name / .Count / .Unread
│   ├── .People    → .List → .Item → .Avatar / .Name / .Count / .Content
│   ├── .List      → .Item → .Avatar / .Body / .FileName / .Headline / .Time / .Unread
│   ├── .LoadMore   .AllReadContainer
└── .Settings
    ├── .Header → .Title   .BackButton  .Description  .Footer  .Title
    ├── .MuteAllTitle  .MuteAllDescription  .MuteAllToggle
    └── .List → .Accordion
        ├── .Trigger → .SelectedValue / .Label / .Icon
        └── .Content → .Item → .Icon / .Label
```

**Key tokens:** `{selectedTab}` (`'forYou'|'people'|'documents'|'all'`), `{TABS}`, `{tabConfig}`, `{settingsOpen}`, `{settingsMutedAll}`, `{notificationsPanelVisible}`, `{unreadNotificationsForYou}` (tool: array → `.length` for the badge), `{notificationsByDate}` / `{notificationsByUserMap}` / `{notificationsByDocumentId}`. Inside the content list: `{notification}` (`.title`, `.from.name`, `.from.photoUrl`, `.read`, `.createdAt`, `.documentName`), `{isLoadMoreVisible}`, `{isAllRead}`.

> Gotchas: `{notification.*}` only resolves **inside** the content-list iteration. `.Title` is a leaf: to change the heading text use the top-level `.TitleText` slot (there's no `.Title.Text`).

## Headless hooks

| Hook | Returns |
| - | - |
| `useNotificationsData(query?)` | `Notification[] \| null` (`query.type`: `'all'\|'forYou'\|'documents'`) |
| `useUnreadNotificationsCount()` | `{ forYou: number\|null, all: number\|null }` (badges) |
| `useNotificationSettings()` | `{ settings, setSettings, setSettingsInitialConfig }` |
| `useNotificationEventCallback(action)` | Event subscription (e.g. settings updated) |
| `useNotificationUtils()` | Imperative element (open/close panel, mark-all-read, mute, tab config, cross-org, …) |

## Limitations

All list rendering flows through the content-list iteration (variables scoped there). Tool-only props (`considerAllNotifications`, `panelShadowDom`, `panelVariant`, `maxDays`) aren't on the panel. Cross-org `feeds:'all'` is ignored (only `forYou`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.