Notification stack

ProReact Native · Expo

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.

View as Markdown

Installation

$ npx shadcn@latest add @goodui-native-pro/notification-stack

Then run npx expo install --fix so react-native-gesture-handler, react-native-reanimated, react-native-svg match your Expo SDK. Files land in components/goodui-native/notification-stack.

Pro components and screens install from the license-gated @goodui-native-pro registry. Setup: Pro access.

Usage

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)}
    />
  );
}

When to use

Use it for
  • 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.
Reach for something else
  • 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.

Examples

A new notification drops in on top

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

Controlled, with your own controls and an empty state

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

<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

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

Motion and haptics

  • 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.
  • Haptic: select when a dragged card crosses the point of no return
  • Haptic: whoosh when a card is dismissed, delete on clear all
  • Haptic: open and close when the pile fans out or folds, receive when a new notification lands
  • 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.

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'.

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).