---
title: Notifications
slug: notifications
kind: pattern
summary: Telling someone that something needs them — with a strict rule about what earns an interruption, because the cost of a wrong one is that all of them get ignored.
problem: >-
  Everything that happens generates a notification, so people mute the product
  or archive without reading. The one message that genuinely needed a person is
  now indistinguishable from forty that did not, and it gets missed.
family: [coordinate, recover]
data_shape: [record]
principles: [surface-dont-bury, friction, orientation]
interaction: [feedback]
density: low
complexity: high
status: stable
visibility: public
use_when:
  - Something happens that a specific person must act on, and they are not looking at the screen.
  - Work is assigned or handed over between people.
  - A deadline or a threshold is passed and nobody would otherwise notice.
avoid_when:
  - The event is something the person did themselves.
  - Nobody needs to act; it is history, and belongs in the timeline.
  - It can wait for the next time they open the product — that is a badge, not a notification.
alternatives:
  - slug: activity-timeline
    when: The event is worth recording but nobody has to be told.
  - slug: review-queue
    when: The volume is high and steady. A queue people work beats interrupting them per item.
ask_leo: |
  Add notifications, and be strict about what qualifies.

  - Notify a person only when they need to ACT, or when something they are
    accountable for has changed. If nobody needs to do anything, it belongs in
    the record's timeline, not in someone's inbox.
  - Never notify someone about their own action.
  - Every notification names the record, says what happened and who did it, and
    links straight to the thing — not to a list.
  - Group related events. Ten comments on one record in ten minutes is one
    notification, not ten.
  - Separate urgency from delivery: in-app for everything, email or SMS only for
    things that cannot wait until the person next opens the product. Let people
    change that per category.
  - Mark as read when the person opens the linked record, not just when they see
    the list. An unread count that does not go down is why people stop looking.
  - Give a real preferences screen, per category, and honour it immediately.
  - Do not send a notification during a bulk action for every affected record.
    Send one summary.
related:
  - title: Comments and Mentions
    url: /patterns/comments-and-mentions
    summary: The most common legitimate trigger — someone named you.
  - title: Assign an Owner
    url: /patterns/assign-owner
    summary: The other one — work became yours.
---

## Anatomy

```
  ┌─ Notifications ───────────────────────── 3 unread ─┐
  │ ● Priya mentioned you on INV-1043        2h ago    │ ← act
  │   "can you check the labour hours before we send?" │
  │ ● JOB-204 was handed to you by Sales     yesterday │ ← act
  │ ● 4 comments on JOB-118                  yesterday │ ← grouped, not 4 rows
  │   Dana, Sam and 1 other                            │
  └────────────────────────────────────────────────────┘
     each row links to the RECORD, not to a list
```

The three rules that decide whether this works:

1. **Only actionable events.** The test is whether a reasonable person would do
   something. If not, it is timeline material.
2. **Grouped.** One record's burst of activity is one row.
3. **Deep links.** A notification that drops you on a dashboard has made you do
   the finding it was supposed to save you.

## Why it works

It works only through restraint, which is why this entry is mostly about what NOT
to send. The engineering is easy and the judgment is hard. Every stakeholder wants
their event notified, each request is individually reasonable, and the
cumulative result is a channel nobody reads.

The failure is not gradual — it is a **cliff**. Up to some volume, people read
notifications. Past it, they mute or bulk-archive, and from that moment the
channel carries nothing, including the important messages. You cannot recover
by adding a priority flag later, because nobody is looking.

So the useful discipline is a budget, like the one on a glance layer: to add a
notification type, justify it against the ones that exist, and be willing to
remove one.

## Urgency is a separate axis from delivery

Two questions, often conflated:

| Question | Answer shapes |
|---|---|
| Does someone need to act? | Notify, or put it in the timeline |
| Can it wait until they next open the app? | In-app only, or email/SMS too |

Most events that deserve a notification do **not** deserve an email. Getting
this wrong is how a product ends up in a mail filter, at which point the in-app
notification is fine and nobody sees the email that mattered.

## Getting it wrong

- **Notifying people about their own actions**, the fastest way to train
  everyone to ignore the icon.
- **One per event during a bulk operation** — forty emails from one click.
- **A count that does not clear** when you read the underlying record.
- **Links to a list**, not the record.
- **No per-category preferences**, so the only available control is "all off".
- **Everything by email**, which puts the product in a filter permanently.

## Exemplars

**GitHub's notification model** is unusually explicit about the distinction:
participating versus watching, and per-repository settings. The lesson is that
the *reason* you got a notification is itself information, and showing it lets
people tune rather than mute.

**Linear** groups aggressively and defaults to in-app, with email reserved for
things assigned to you. The result is a notification list people actually read.

**Slack's @-here versus @-channel** is the clearest demonstration of the cliff:
the moment a workspace normalises broad mentions, everyone mutes the channel and
the mechanism is dead for everyone.

The extractable rule: **notifications are a budget, not a feature.** Every one
you add spends attention that the important ones need, and the failure mode is
sudden and permanent.