> ## Documentation Index
> Fetch the complete documentation index at: https://velt-codex-ui-customization-guide-refresh.mintlify.site/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.

## Components

|                        | 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)          |
| `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`, R9b.) Tool: `velt-notifications-tool`, `active` / `velt-notification-tool-open` (panel open). Tabs: `velt-notifications-panel--tab`, `velt-notifications-panel--tab-selected` (active tab). Panel mode: `velt-notifications-panel--sidebar-panel`, `bottom-sheet`. Unread: `velt-notifications-panel--list-item-unread`, `velt-notifications-panel--unread-is-default`. Settings accordion: `velt-notification-panel--settings-accordion-container-expanded` / `…-open`; mute toggle: `velt-notification-panel--settings-mute-all-toggle-container-muted`.

## Wireframes: slot trees + tokens

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

**`VeltNotificationsPanelWireframe`** (abridged: full depth below):

```
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

* `useNotificationsData(query?)` → `Notification[] | null` (`query.type`: `'all'|'forYou'|'documents'`).
* `useUnreadNotificationsCount()` → `{ forYou: number|null, all: number|null }` (badges).
* `useNotificationSettings()` → `{ settings, setSettings, setSettingsInitialConfig }`.
* `useNotificationEventCallback(action)` (e.g. settings updated); `useNotificationUtils()` for the 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`).