# Notification stack

> A lock screen style pile of notification cards: collapsed, each card behind is smaller, lower and dimmer; a tap fans the pile into a list on a staggered spring, any card follows the finger 1:1 and leaves with its velocity while the rest close the gap, a new one drops in on top, and clear all sweeps them off one after another.

- Type: Component (feedback)
- Access: Pro
- Page: https://goodui.dev/native/components/notification-stack
- Markdown: https://goodui.dev/native/components/notification-stack.md
- Registry item: https://goodui.dev/native/r/notification-stack.json
- Dependencies: react-native-gesture-handler, react-native-reanimated, react-native-svg
- Keywords: react native notification stack, notification center, lock screen notifications, stacked cards expand, swipe to dismiss notification, notification list clear all, grouped notifications expo

## When to use

- A notification centre or activity feed inside a screen where a pile saves room until someone wants the whole list.
- A home or lock style screen with grouped alerts: deliveries, messages, payments, reminders.
- Any short queue of cards a person works through by swiping them away: approvals, tasks for today, new matches.

## When not to use

- A passing confirmation that leaves by itself: use toast, which floats above the screen and times out.
- One persistent message tied to the screen (offline, payment failed): use banner.
- A full inbox with sections, read state and hundreds of rows: use notifications-screen or a list of swipe-actions rows.
- Inside a horizontally scrolling parent: the sideways swipe would fight it.

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add @goodui-native-pro/notification-stack
npx expo install --fix
```

Pro: add `"@goodui-native-pro": { "url": "https://goodui.dev/native/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${GOODUI_LICENSE_KEY}" } }` to the `registries` of components.json and put your license key in .env.local.

The component lands in `components/goodui-native/notification-stack/` and imports the foundation from `components/goodui-native/foundation/` with relative paths; it also installs locale.

Built-in strings follow `<GooduiLocaleProvider>` (one [language pack](https://goodui.dev/native/r/locale-tr.json) translates the whole kit); the `labels` prop overrides them for one instance.

## Usage

```tsx
import { useState } from "react";
import { NotificationStack, type NotificationStackItem } from "@/components/goodui-native/notification-stack/notification-stack";

const first: NotificationStackItem[] = [
  { id: "1", title: "Maya Chen", body: "Running ten minutes late. Grab the table by the window?", time: "now" },
  { id: "2", title: "Payment received", body: "€240.00 from Studio Nord", time: "9m" },
  { id: "3", title: "Design review in 15 min", body: "Room Atlas, or join the call", time: "24m" },
];

export function NotificationCentre() {
  const [items, setItems] = useState(first);
  return (
    <NotificationStack
      items={items}
      title="Notification Centre"
      onDismiss={(item) => setItems((list) => list.filter((n) => n.id !== item.id))}
      onClear={() => setItems([])}
      onItemPress={(item) => console.log("open", item.id)}
    />
  );
}
```

## Examples

### A new notification drops in on top

```tsx
setItems((list) => [{ id: String(Date.now()), title: "Order shipped", body: "Arrives Thursday", time: "now" }, ...list]);
```

### Controlled, with your own controls and an empty state

```tsx
const stack = useRef<NotificationStackHandle>(null);
const [expanded, setExpanded] = useState(false);

<Button onPress={() => stack.current?.clear()}>Clear all</Button>
<NotificationStack
  ref={stack}
  items={items}
  expanded={expanded}
  onExpandedChange={setExpanded}
  onDismiss={(item) => remove(item.id)}
  onClear={() => setItems([])}
  empty={<Text tone="secondary">You're all caught up.</Text>}
/>
```

### Your own card layout

```tsx
<NotificationStack
  items={parcels}
  defaultExpanded
  onDismiss={(item) => remove(item.id)}
  renderItem={({ item }) => (
    <View style={{ padding: 12, gap: 8 }}>
      <Text weight="medium">{item.title}</Text>
      <Text size="footnote" tone="secondary">{item.body}</Text>
    </View>
  )}
/>
```

## API reference

### NotificationStack

`import { NotificationStack } from "@/components/goodui-native/notification-stack/notification-stack";`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `T[]` | – | The notifications, newest first. Remove an item in `onDismiss` and empty the list in `onClear`. |
| `renderItem` | `(info: { item: T; index: number; expanded: boolean }) => ReactNode` | – | Draws the inside of a card instead of the default icon, title, body and time. The stack keeps the surface, the motion and the gestures. |
| `title` | `string` | – | Heading of the open list, for example "Notification Centre". Defaults to the count. |
| `expanded` | `boolean` | – | Whether the list is fanned out (controlled). Pair with `onExpandedChange`. |
| `defaultExpanded` | `boolean` | `false` | Start fanned out (uncontrolled). Default `false`. |
| `onExpandedChange` | `(expanded: boolean) => void` | – | Called when the pile is tapped open, folded with the collapse control, or folds by itself because one card is left. |
| `onDismiss` | `(item: T, index: number) => void` | – | Called the moment a card is swiped away (or removed through the handle or a screen reader action). |
| `onClear` | `() => void` | – | Called when "clear all" starts sweeping the cards off. |
| `onItemPress` | `(item: T, index: number) => void` | – | Called when a card in the open list (or a pile of one) is tapped. |
| `maxVisible` | `number` | `3` | How many cards show in the collapsed pile, 1 to 4. Default 3. |
| `empty` | `ReactNode` | – | Shown once the last card has left, for example "You're all caught up". |
| `cardStyle` | `StyleProp<ViewStyle>` | – | Style of every card surface (background, border color). Keep the background opaque: cards overlap in the pile. |
| `haptic` | `boolean` | `true` | Haptics: a tick at the point of no return, on dismiss, on fold and unfold, and when a new card lands. Default `true`. |
| `ref` | `Ref<NotificationStackHandle>` | – | Imperative handle: `ref.current?.expand()`, `collapse()`, `dismiss(id)`, `clear()`. |
| `labels` | `Partial<NotificationStackLabels>` | – | Overrides for the built-in strings; a GooduiLocaleProvider pack sets them app-wide. |
| `style` | `StyleProp<ViewStyle>` | – | Style for the outer container. |
| `testID` | `string` | – | Identifier for end-to-end tests. |

## Accessibility

- Collapsed, the pile is one button named with the count and the front notification ("4 notifications. Maya Chen. Running late. now"), with expanded: false in accessibilityState; activating it opens the list. The cards behind are hidden from screen readers.
- In the open list every card is a button named with its title, body and time. Swiping has an equivalent: the custom accessibility action Dismiss on each card removes it the same way and calls onDismiss.
- The header's Show less and Clear all are buttons; the header text has the header role. They are removed from focus while the pile is collapsed.
- On the web a focused card takes Enter or Space (open the pile or press the card), Delete or Backspace (dismiss) and Escape (fold the list).
- A new notification is announced with its title and body; after a dismissal the remaining count is announced; after clear all, 'Notifications cleared'.

## Motion

- Collapsed: each card behind the front one is 5.5% smaller, 10 pt lower and dimmer, clipped to the front card's height with its content faded out, so the pile reads as blank slabs under one message.
- Fan out: every card springs from its place in the pile to its row on the morph spring, 45 ms apart from the front card down; the header fades up and the container grows on smooth. Folding runs from the far end back on smooth.
- Swipe: the card follows the finger 1:1 in either direction and gives to 0.98 on touch down. Past 38% of the width (a tick marks it) or on a flick over 700 pt/s it leaves on a spring that carries the finger's velocity and fades out past the halfway point; released earlier it springs back on snappy with the same velocity.
- Closing the gap: the cards below a removed one spring up on morph. In the pile, the cards behind rise toward the front 1:1 with the front card's drag.
- Arrival: a new card drops in from above the pile on the bouncy spring while the others step back.
- Clear all: the cards leave toward the end edge 70 ms apart, each with a velocity kick; the space they held closes only after the last one has started.
- Reduced motion: the card still follows the finger, but releases, arrivals and removals fade in place, the pile and the list swap without travel or stagger, and nothing bounces.

## Haptics

- select when a dragged card crosses the point of no return
- whoosh when a card is dismissed, delete on clear all
- open and close when the pile fans out or folds, receive when a new notification lands

## Performance

- Drags, releases and every spring run on the UI thread through Gesture Handler and Reanimated. React renders only when a card arrives, leaves, is measured, or the pile opens or folds.
- Every card stays mounted and absolutely positioned; card heights and the container height animate as layout. Built for up to a few dozen notifications: page or trim longer lists.

## Notes for AI

- items is the source of truth, newest first, each with a stable unique id. Remove the item in onDismiss and empty the list in onClear; the exit animation still plays after the item is gone from the array.
- To show a new notification, put it at index 0 with a new id. Do not remount the stack or change its key.
- renderItem draws only the inside of the card (start with your own padding, 12 pt matches the default). The stack owns the surface, radius, shadow and gestures. Do not put Pressables inside a card: use onItemPress.
- Keep title on every item even with renderItem: it is what screen readers read.
- expanded is optional; without it the stack manages itself. With one card left it folds by itself and calls onExpandedChange(false).
- cardStyle may change the surface color or border, but the background must be opaque because cards overlap in the pile.
- time is a string you format ("now", "2m"); the component does no date math.
- It stretches to its parent's width and animates its own height, so content below moves with it. Give the parent a minHeight if that content should stay still.
- Requires GestureHandlerRootView at the app root (see the foundation setup).

## Related

- [Toast](https://goodui.dev/native/components/toast.md): Background confirmations that stack at the top, fan out on tap, swipe away up or sideways, and pause their timers while touched.
- [Banner](https://goodui.dev/native/components/banner.md): An inline status banner that slides down from under the edge above and pushes the content down, flings away sideways with the finger, and can collapse on its own behind a draining hairline; includes an offline preset.
- [Notifications screen](https://goodui.dev/native/components/notifications-screen.md): Activity grouped into Today and Earlier with avatars, unread dots and thumbnails, follow requests with Accept and Decline in the row, swipe to dismiss, Mark all read where the dots fold away one after another, a banner that offers to turn on push while it is off, and an empty state when everything is cleared.
- [Swipe actions](https://goodui.dev/native/components/swipe-actions.md): Row actions that unfold with the finger; a long swipe lets the edge action take over and run, and destructive actions collapse the row before it leaves.

## Guidance for AI tools

Notification stack: A lock screen style pile of notification cards: collapsed, each card behind is smaller, lower and dimmer; a tap fans the pile into a list on a staggered spring, any card follows the finger 1:1 and leaves with its velocity while the rest close the gap, a new one drops in on top, and clear all sweeps them off one after another. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt
