Dynamic island
ProReact Native · ExpoA black pill at the top of the screen that hosts live activities and morphs between a compact pill with a slot at each end, a pill with a detached bubble for a second activity, and an expanded panel that follows a vertical drag 1:1.
Installation
$ npx shadcn@latest add @goodui-native-pro/dynamic-islandThen run npx expo install --fix so react-native-gesture-handler, react-native-reanimated match your Expo SDK. Files land in components/goodui-native/dynamic-island.
Pro components and screens install from the license-gated @goodui-native-pro registry. Setup: Pro access.
Usage
import { useRef, type ReactNode } from "react";
import { Text } from "react-native";
import { DynamicIsland, type DynamicIslandHandle } from "@/components/goodui-native/dynamic-island/dynamic-island";
import { TimerIcon } from "@/components/icons";
// Render one island near the app root, then drive it from anywhere through the ref.
export function AppShell({ children }: { children: ReactNode }) {
const island = useRef<DynamicIslandHandle>(null);
const startTimer = () =>
island.current?.show({
id: "timer",
accessibilityLabel: "Timer, 4 minutes 32 seconds left",
leading: <TimerIcon color="orange" size={20} />,
trailing: <Text style={{ color: "orange", fontVariant: ["tabular-nums"] }}>4:32</Text>,
expanded: <Text style={{ color: "white", fontSize: 40 }}>4:32</Text>,
});
return (
<>
{children}
<DynamicIsland ref={island} idle="hidden" />
</>
);
}When to use
- Something keeps running while the person moves around the app: a timer, a ride, a delivery, a recording, playback, a call.
- A short confirmation that should not cover content or take the bottom of the screen: a payment sent, a device connected.
- Giving Android and the web the same live activity surface an iPhone has, inside your own app.
- Messages that need an action button or a queue: use toast or banner.
- Blocking decisions: use alert-dialog.
- System-wide Live Activities outside your app on iOS: those need ActivityKit; this component draws inside the app only.
Examples
A toast: opens as a panel and leaves by itself
island.current?.show({
id: "paid",
accessibilityLabel: "Sent €24.00 to Maya",
startExpanded: true,
duration: 2400,
expanded: <PaidRow amount="€24.00" to="Maya" />,
});Update in place, then dismiss
island.current?.update("timer", { trailing: <Digits value={left} /> });
island.current?.dismiss("timer");Controlled
<DynamicIsland
activities={activities}
onActivitiesChange={setActivities}
expanded={open}
onExpandedChange={setOpen}
/>Inside a framed preview instead of the overlay layer
<View style={{ height: 240 }}>
<DynamicIsland portal={false} activities={activities} />
</View>API reference
| Prop | Type | Default |
|---|---|---|
| ref Imperative handle: `ref.current?.show({ id, leading, trailing, expanded, accessibilityLabel })`. | Ref<DynamicIslandHandle> | — |
| activities The live activities (controlled). The last one holds the pill, the one before it sits in the bubble. | DynamicIslandActivity[] | — |
| onActivitiesChange Called with the next list when the island adds, reorders or drops an activity. | (activities: DynamicIslandActivity[]) => void | — |
| expanded Whether the panel of the front activity is open (controlled). | boolean | — |
| onExpandedChange Called when a tap, a drag, a tap outside or the timeout opens or folds the panel. | (expanded: boolean) => void | — |
| collapseAfter Fold a panel the person opened after this many ms without a touch. `false` keeps it open. Default 6000. | number | false | 6000 |
| idle What shows with no activity: the bare `pill`, or nothing. | "pill" | "hidden" | "pill" |
| portal Render in the overlay layer above the app. With `false` it sits at the top of its parent, for a framed preview. | boolean | true |
| topOffset Distance below the top safe area inset. Default 8. | number | 8 |
| maxWidth Widest the expanded panel gets. Default 380. | number | 380 |
| color Island color. Content is drawn on it, so keep it near black. | string | ISLAND |
| testID Identifier for end-to-end tests. | string | — |
Motion and haptics
- Width, height and corner radius move together on the morph spring: bare pill, compact pill sized to its two slots, expanded panel sized to its content.
- Content crossfades: the slots fade and shrink away in the first third of the morph, the panel is laid out at its final size and scales up with the island's width while it fades in, so it is never cut off mid-morph. A new activity's content fades in as the previous one fades out.
- A second activity buds off as a bubble: it slides out from under the trailing end of the pill while the pill shifts aside, on the morph spring. Opening the panel pulls the bubble back in.
- Touch down: the pill gives to 0.95 on the snappy spring.
- Drag: pulling the pill down opens it and pushing the panel up folds it, 1:1 with the finger; past either end it stretches with resistance. Release settles open or closed from the projected position, carrying the finger's velocity into the morph spring.
- A panel the person opened folds by itself after collapseAfter (6 s) without a touch. A panel that opened by itself (startExpanded) stays until it is dismissed, its duration ends or the person folds it.
- Reduced motion: shapes jump to their end state and content swaps without travel; drags still follow the finger.
- Haptic: open when the person opens the panel by tap or drag
- Haptic: Nothing when an activity appears or leaves by itself.
- The morph and the drag run on the UI thread from shared values. React renders when the list of activities or the open state changes, and when your slot content changes.
- Slots and panels are measured with onLayout: the compact width and the panel height follow their content, so nothing has to be sized by hand.
- Every live activity stays mounted (only the front one is visible), so a ticking timer keeps its state while another activity holds the pill.
Accessibility
- The compact island is one button named by the activity's accessibilityLabel, with its expanded state; a double tap (or Enter and Space on the web) opens the panel, or calls onPress when there is no panel.
- When an activity takes the pill its accessibilityLabel is announced.
- While the panel is open the island stops being a single element, so the controls inside it are reachable, and it is marked as modal. The escape gesture, Escape on the web and the Android back button fold it.
- The bubble is a button named by the second activity; activating it swaps the two.
- The bare pill with no activity is hidden from screen readers.
- Content sits on black whatever the theme: use light text and icons inside the slots and the panel.
Notes for AI
- Render exactly one DynamicIsland near the app root and call it through the ref (show, update, dismiss, expand, collapse), or control it with activities and onActivitiesChange. Do not mount one per screen.
- The last activity in the list holds the pill; the one before it sits in the bubble. show() of an id that is already live replaces it and brings it to the front; use update() for content that changes in place.
- Every activity needs accessibilityLabel. leading and trailing are small (about 24 pt tall); expanded is the panel and gets 20 pt of padding from the island.
- The island is always near black: style slot and panel content with light colors, not theme foreground colors.
- It is placed under the top safe area inset. It does not draw around a hardware cutout and does not create iOS Live Activities.
- When expanded is controlled, follow onExpandedChange: the island reports taps, drags, tap outside and the timeout through it.
- Requires ThemeProvider (for the overlay layer) and GestureHandlerRootView at the app root.
Related
Background confirmations that stack at the top, fan out on tap, swipe away up or sideways, and pause their timers while touched.
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.
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.