Notifications widget

Bell icon with an unread badge in your header. Clicking opens an in-place drawer (Activity + Requests tabs) with the user's notifications and pending friend requests. The drawer renders the same on every page that mounts the widget — community-app pages and customer landing pages alike, no host wiring required.

Install

<script src="/widgets/v1/notifications.js" async></script>
<div data-cobuntu-notifications></div>

The bell renders inline at the mount node. Theme is auto-fetched from the community config — see Theming for how to override.

What the drawer shows

Two tabs:

Activity — your notification feed (paginated, 50 most recent). Each row has the actor avatar (with a per-type icon overlay), a message line, an optional snippet, and time-ago. Notifications about posts also show a 44×44 thumbnail of the post media on the right. Multiple notifications about the same post collapse into one row ("Becky and 3 others reacted to your post"). Rows in the Activity tab are grouped by recency under section headers — Today, Yesterday, This Week, This Month, Earlier.

Requests — pending friend requests with inline Accept / Reject buttons. The Requests tab carries a small count badge when there's anything pending.

Opening the drawer auto-marks all unread notifications as read (clears the badge).

Behavior knobs (data attributes)

Attribute	Values	Default	Effect
`data-variant`	`icon` \| `button`	`icon`	Bell only vs. bell + label
`data-size`	`sm` \| `md` \| `lg`	`md`	Trigger size
`data-show-badge`	`true` \| `false`	`true`	Show the unread count pip
`data-label`	string	`Notifications`	aria-label
`data-button-label`	string	`Notifications`	Label text (button variant)
`data-require-auth`	`prompt` \| `hide`	`prompt`	What unauth visitors see

Styling

All visual tokens are CSS custom properties — see Theming for the full var list. The drawer specifically uses:

--cobuntu-drawer-bg          drawer background (falls back to --cobuntu-bg)
--cobuntu-drawer-color       drawer text (falls back to --cobuntu-color)
--cobuntu-badge-bg           unread pip + per-type "people" overlay
--cobuntu-radius             button corners
--cobuntu-primary-btn-bg     Accept button (Requests tab)
--cobuntu-primary-btn-text   Accept button text

Render-yourself slot (Level 3)

If you want to fully replace the bell with your own markup but still pick up the live unread count + open behavior:

<div data-cobuntu-notifications>
  <button data-cobuntu-action="open-notifications" class="my-class">
    My custom bell
    <span data-cobuntu-bind="unread-count" data-cobuntu-show="has-unread">0</span>
  </button>
</div>

The widget detects the custom slots and binds behavior + state to them. Available bindings:

Slot	Behavior
`data-cobuntu-bind="unread-count"`	Receives the live unread count as text
`data-cobuntu-show="has-unread"`	Visible only when unread > 0
`data-cobuntu-show="no-unread"`	Visible only when unread is 0
`data-cobuntu-action="open-notifications"`	Click opens the drawer

Click-through routes

When the user clicks a notification row, the widget navigates within the community surface. The destination depends on the notification type:

Type	Where the click lands
`FRIEND_REQUEST_INBOUND`	`/members/<usertag>` of the sender
`FRIEND_REQUEST_ACCEPTED`	`/members/<usertag>` of the accepter
`FRIENDSHIP_CONFIRMED`	`/members/<usertag>` of the friend
`MEMBERSHIP_REQUEST`	`/members` (the directory)
`MEMBERSHIP_CONFIRMED`	`/` (community home)
`MEMBERSHIP_KICKED_USER`	not clickable (read-only)
`FEED_MENTIONED`	`/feed/post/<messageId>`
`POST_REACTED`	`/feed/post/<postId>`
`POST_COMMENTED`	`/feed/post/<postId>`
`POST_COMMENT_REPLY`	`/feed/post/<postId>`
`POST_COMMENT_LIKED`	not clickable
`POST_MENTIONED`	`/feed/post/<postId>`
`POST_STAR_ACHIEVED`	not clickable
`POST_REMOVED_FROM_COMMUNITY`	not clickable
`LISTING_REQUESTED`	not clickable
`LISTING_APPROVED`	not clickable
`LISTING_REJECTED`	not clickable
`LISTING_DEACTIVATED`	not clickable
`LISTING_WITHDRAWN`	not clickable
`LISTING_PROPOSAL`	not clickable
`LISTING_PROPOSAL_ACCEPTED`	not clickable
`LISTING_PROPOSAL_REJECTED`	not clickable

Read-only rows still show the per-type icon, message and timestamp; they just don't navigate when clicked. New types added to the backend render with a generic "New activity" message so a future enum value never breaks the drawer.

Public API

See Programmatic API for the full surface. Quick reference:

window.CobuntuNotifications = {
  unread(): number;
  refresh(): Promise<void>;
  open(): void;
  close(): void;
};

Versioning

v1 is stable. The drawer's HTML structure, CSS class names, and JS API are frozen for the v1 line. A future v2 may change the drawer layout (e.g. a popover instead of a side panel); it will ship at /widgets/v2/notifications.js and both versions will coexist for the standard deprecation window.

Messages Search