# islandcn

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

## 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. Read [Installation](https://islandcn.dev/docs/installation.md) to install the engine and mount the island.
2. Read [Activities](https://islandcn.dev/docs/guides/activities.md) to start, update and end one for the app's own actions.
3. Build one by hand in the [playground](https://islandcn.dev/playground.md) and copy its code.

Coding agents can install the islandcn skill as an install helper: `npx shadcn@latest add https://islandcn.dev/r/islandcn-skill.json`, then follow it (https://islandcn.dev/.well-known/agent-skills/islandcn/SKILL.md).

## Getting started

- [Overview](https://islandcn.dev/docs.md): islandcn is the open-source Dynamic Island for React. It shows what your app is doing in one black pill at the top of the page.
- [Installation](https://islandcn.dev/docs/installation.md): Add the islandcn engine to a React project with the shadcn CLI and mount the island once.
- [Quick start](https://islandcn.dev/docs/quick-start.md): Start an activity from a button, update it while the task runs, and end it when the task is done.

## Guides

- [Activities](https://islandcn.dev/docs/guides/activities.md): Start an activity when a task begins, update it as the task moves, and end it when the task is done.
- [Compact, expanded and split](https://islandcn.dev/docs/guides/presentations.md): The four shapes the island takes, which one shows when, and how to write content that fits each.
- [Actions](https://islandcn.dev/docs/guides/actions.md): What taps, long-presses and keys do to the island, how to add buttons to the expanded view, and when to alert.
- [Theming](https://islandcn.dev/docs/guides/theming.md): Match the island to your page with the keyline, accent colours and the content kit's type, and keep the pill itself black.
- [Motion and reduced motion](https://islandcn.dev/docs/guides/motion.md): How the island's springs work, how to change them, and what changes when the user asks for reduced motion.

## Presets

- [Presets](https://islandcn.dev/docs/presets.md): Nine finished islands built on the engine, one file each. Install one as it is, or read it for technique and build your own.
- [Upload](https://islandcn.dev/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](https://islandcn.dev/docs/presets/timer.md): A countdown with the time left on the trailing side and pause and cancel buttons when expanded.
- [Now playing](https://islandcn.dev/docs/presets/now-playing.md): Artwork on the leading side, a live level meter on the trailing side, transport controls when expanded.
- [Incoming call](https://islandcn.dev/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](https://islandcn.dev/docs/presets/eta.md): Minutes until a ride or delivery arrives, with the driver, the vehicle and an optional Message button.
- [Recording](https://islandcn.dev/docs/presets/recording.md): A recording indicator with an elapsed timer and a level meter, for audio, screen or camera capture.
- [Nearby transfer](https://islandcn.dev/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](https://islandcn.dev/docs/presets/battery.md): Charge level and charging state, shown briefly when power connects or runs low.
- [Split](https://islandcn.dev/docs/presets/split.md): Two activities at once: one stays attached to the pill, the other moves to a capsule beside it.

## API reference

- [Island](https://islandcn.dev/docs/api/island.md): Draws the activity stack from the nearest IslandProvider at the top centre of its container or of the window.
- [IslandProvider](https://islandcn.dev/docs/api/island-provider.md): Owns the activity stack and the clock for every Island and useIsland below it, and takes the metrics, motion and reduced-motion settings.
- [useIsland](https://islandcn.dev/docs/api/use-island.md): The hook that starts, updates, expands and ends activities, and reports what the island shows.
- [ActivityOptions](https://islandcn.dev/docs/api/activity-options.md): The object you pass to start: an id, a label, a priority, and the content for compact, minimal and expanded.
- [IslandNumber and IslandProgress](https://islandcn.dev/docs/api/primitives.md): Content primitives that animate a changed number or a moving bar on the island's clock, as a live status activity's content does.
- [Content kit](https://islandcn.dev/docs/api/content-kit.md): The pieces island content is built from: text styles, layout frames, glyphs, rings, bars, steps, sparklines, readings and clocks, one registry item each.

## More

- [Agent skill](https://islandcn.dev/docs/agent-skill.md): An optional install helper for coding agents: the islandcn skill sets up the engine and wires an activity to your app.
- [How it's measured](https://islandcn.dev/docs/how-its-measured.md): islandcn's sizes and springs come from simulator recordings of the reference phone, compared with the web version frame by frame.

## Other resources

- [Full docs in one file](https://islandcn.dev/llms-full.txt)
- [Playground](https://islandcn.dev/playground.md)
- [Agent skills index](https://islandcn.dev/.well-known/agent-skills/index.json)
- [Registry index](https://islandcn.dev/r/registry.json)