# islandcn: The open-source Dynamic Island for React

islandcn is the open-source Dynamic Island for React, installed with shadcn. It shows uploads, timers, calls, rides and music in one animated pill at the top of any web app, and you shape each activity around your app's own actions.

> For the full documentation index, see [llms.txt](http://localhost:3000/llms.txt). Every page has a Markdown version: add `.md` to its URL or send `Accept: text/markdown`. To build an island, follow the islandcn agent skill at http://localhost:3000/.well-known/agent-skills/islandcn/SKILL.md.

## Start here

islandcn is an engine, not a component menu. The presets are examples of what the engine draws. When a user asks for an island, build the one they asked for on the engine (`@/lib/island`), and read the closest preset's source only for technique.

1. Install the engine: `npx shadcn@latest add http://localhost:3000/r/island-core.json`.
2. Mount `IslandProvider` and `<Island placement="viewport" />` once, then start activities with `useIsland()`: [Installation](http://localhost:3000/docs/installation.md).
3. Build the island for the app's own actions, or copy one from the [playground](http://localhost:3000/playground).

Coding agents can install the islandcn skill as a helper: `npx shadcn@latest add http://localhost:3000/r/islandcn-skill.json` (also at http://localhost:3000/.well-known/agent-skills/islandcn/SKILL.md).

## Presets

- [Upload](http://localhost:3000/docs/presets/upload.md): A photo or file upload, as a posting app shows it: the thumbnail, a ring with the percentage, and a check when it lands.
- [Timer](http://localhost:3000/docs/presets/timer.md): A countdown with the time left on the trailing side and pause and cancel buttons when expanded.
- [Now playing](http://localhost:3000/docs/presets/now-playing.md): Artwork on the leading side, a live level meter on the trailing side, transport controls when expanded.
- [Incoming call](http://localhost:3000/docs/presets/incoming-call.md): A caller's name with accept and decline buttons, expanded while it rings, then a call timer.
- [Ride or delivery ETA](http://localhost:3000/docs/presets/eta.md): Minutes until a ride or delivery arrives, with a route bar from pickup to drop-off.
- [Recording](http://localhost:3000/docs/presets/recording.md): A recording indicator with an elapsed timer and a level meter, for audio, screen or camera capture.
- [Nearby transfer](http://localhost:3000/docs/presets/transfer.md): A photo or file going to a device nearby, or coming from it: who it goes to, the photo on its corner, and a ring with a stop button.
- [Battery](http://localhost:3000/docs/presets/battery.md): Charge level and charging state, shown briefly when power connects or runs low.
- [Split](http://localhost:3000/docs/presets/split.md): Two activities at once: one stays attached to the pill, the other moves to a capsule beside it.

## Links

- [Playground](http://localhost:3000/playground.md)
- [Docs](http://localhost:3000/docs.md)
- [llms.txt](http://localhost:3000/llms.txt) and [llms-full.txt](http://localhost:3000/llms-full.txt)
- [Agent skills index](http://localhost:3000/.well-known/agent-skills/index.json)
- [Registry index](http://localhost:3000/r/registry.json)