Quick Answer: A React Dynamic Island is a status bar pinned to the top of your app that shows live activities such as uploads, timers, or incoming calls. islandcn is an open-source React Dynamic Island component you install with shadcn, mount once near your app root, and drive from any component with useIsland().

Most people first meet a dynamic island on a phone and assume it's a visual flourish. Build one for a web app and the opposite becomes clear: the pixels are the easy part. The hard part is deciding which activity owns the top slot when an upload finishes while a timer runs and a ride is three minutes out. islandcn is an open-source React Dynamic Island built around that queue. Here's how it works, where it bites, and where it stops.

What islandcn Actually Is

islandcn, published by opencoredev on GitHub, is a Dynamic Island-style component for any React app. You install it with the shadcn CLI, which copies source files into your project rather than pulling in an opaque package. That matters. You own the code, you can read the springs, and you can change the behaviour when your app needs something different.

The project has three layers. The engine lives in lib/island/ and ships as the island-core registry item. It handles the activity stack, four presentations, long-press, alerts, and reduced motion. On top sit presets in components/islandcn/ for uploads, timers, now playing, incoming calls, ride or delivery ETAs, recordings, nearby transfers, battery, and a split layout. Each preset is a single file built on the engine.

The third layer is a playground at /playground, where you assemble an island from a preset or a blank activity, fire every action, tune the motion, and copy the install command and code. It's the fastest way to see the model before you write any integration code.

Install It and Mount It Once

Setup takes three steps, and the order matters because the hook only works inside the provider.

  1. Run the install command from the README: npx shadcn@latest add https://islandcn.dev/r/island-core.json.
  2. Wrap your app root in IslandProvider and place <Island placement="viewport" /> inside it, next to your app tree.
  3. From any child component, call useIsland() and start an activity with an id, a label, and compact and expanded slots.

Mount it once. A second provider means a second, disconnected stack, and you'll spend an afternoon wondering why an activity you started never appears. Mounting at the root is the simplest way to keep one source of truth.

Once the island is mounted, starting an activity returns a handle. Call update() on that handle to change the compact trailing slot, such as a progress ring going from 0.4 to 0.8, and call end() when the work finishes. Here's the part most guides skip: an activity only leaves the screen when you end it. If you forget end() on an error path, the island keeps showing a finished upload. Wrap your async work in try/finally so the activity always closes.

Think in Activities, Not a Single Widget

The common advice for a status bar component is to build one widget with a state variable and switch its content. That works for a single thing. It breaks the moment two things are live at once.

islandcn takes the opposite view. Each activity is a named entry with its own id and lifecycle, and the engine decides which one is presented at a given moment. That's why you can run an upload and a timer at the same time without writing priority logic yourself.

Here's the counter-intuitive part. Most of the work in a Dynamic Island is not rendering; it's lifecycle. You'll spend more time on which activity starts, updates, and ends than on the JSX inside a slot. Treat your island as a stack of ids you own, and name each id after the real operation it tracks, such as upload:report-123, so you can reason about it when something stalls.

Choose Between the Four Presentations

The engine exposes four presentations, and knowing which one a user sees is most of the design work.

PresentationWhat it showsTypical use
IdleNothing active; the island sits as a quiet pillDefault resting state when no activity is running
CompactLeading and trailing slots beside the pillBackground work such as an upload or timer
SplitTwo compact pieces divided across the pillTwo concurrent activities that both need a glance
ExpandedCenter, bottom, and detail slotsActions the user must see or tap, like a call or delivery ETA

The trade-off is information density against interruption. Compact keeps the user in their flow, while expanded asks for attention. Use expanded only when the user has a decision to make. A progress bar that expands on every file upload trains people to ignore the island.

Motion, Long-Press, and Reduced Motion

islandcn's springs were fitted to frame-by-frame recordings of the real island. That is a meaningful claim, and the README is honest about its limits. The recordings aren't in the repository, /compare has nothing to show, and the one test that reads them is skipped. So you can trust the motion as a designed, tunable starting point, but you can't independently verify the fit from the repo alone. The /lab page still plays every transition from its built-in sequences during pnpm dev, which is the best place to inspect them.

Long-press is the other interaction worth understanding. It lets users reach more detail without a permanent UI cost. Use it for secondary actions, not primary ones. A call answer button hidden behind a long-press is a bad product decision, because most users won't discover it.

Reduced motion is part of the engine, not an afterthought. If a user has asked their OS for less motion, the island should reduce its animation rather than ignore the setting. Test this by toggling the system preference, not by assuming the engine handles it in your specific layout.

Presets or Your Own Activity?

Presets are the fastest path. Upload, timer, now playing, incoming call, ride ETA, and recording cover the most common cases, and each is a single file you can copy and edit. The trade-off is that a preset carries the layout decisions of its author. If your upload needs a cancel button and the preset doesn't have one, you'll edit the file. That's fine, and it's the reason the source is in your project.

Build a blank activity when your use case doesn't match a preset. Start with the compact and expanded slots, then add content only as users need it. Overbuilt islands are a common failure: four trailing icons and a bottom progress bar in every state make the island unreadable at a glance.

Licensing and What You Can Copy

islandcn is MIT licensed, copyright 2026 Leo, so you can use it in commercial work with the notice preserved. Read the LICENSE file in the repository before shipping, since the license text is the authoritative version.

The license covers the code, not the look. The README says islandcn copies the look and motion of Apple's island but none of Apple's assets, and it isn't affiliated with Apple. Dynamic Island is a trademark of Apple Inc. In practice, this means you can build a Dynamic Island-style bar, but you shouldn't use Apple's name or logo to market your product as an official feature. Keep the name generic in your own product copy. This isn't legal advice, but it's the conservative reading of what the project itself states.

Frequently Asked Questions

What is a React Dynamic Island component?

A React Dynamic Island is a UI component that displays live activities, such as uploads, timers, or calls, in a pill-shaped bar at the top of an app. It manages a stack of activities and shows the one that matters most. islandcn is an open-source example that you install with shadcn and drive through a useIsland() hook.

How do I add a Dynamic Island to my React app?

Run npx shadcn@latest add https://islandcn.dev/r/island-core.json, wrap your root in IslandProvider, and render <Island placement="viewport" /> once. Then call useIsland().start() from any child component with an id, a label, and slot content. Call end() when the work finishes, and wrap async work in try/finally so the activity always closes.

Why does my island activity never disappear?

The most common cause is a missing end() call, often on an error path. An activity stays in the stack until you end it, so a failed upload that never closes will keep showing. Name each id after the real operation, and wrap the work so the end call runs in every branch.

Should I use the expanded presentation for every activity?

No. Expanded asks for attention, so reserve it for actions the user must see or decide on, such as an incoming call or a delivery ETA. Use compact for background work like uploads and timers. Overusing expanded trains users to ignore the island.

Is islandcn affiliated with Apple?

No. The README states that islandcn isn't affiliated with Apple and copies the look and motion of Apple's island without using any of Apple's assets. Dynamic Island is a trademark of Apple Inc., so avoid implying an official connection in your product's name or marketing.

Wrap Up

A React Dynamic Island is mostly a lifecycle problem, and islandcn gives you a tidy engine for it: one provider, a stack of named activities, and four presentations you can reason about. Mount it once at the root, give every activity an id tied to a real operation, and make sure every start has a matching end. Try the playground this week, fire an upload and a timer together, and note which one wins the top slot. Pass this to anyone wrestling with a React Dynamic Island that never clears.