# islandcn (opencoredev/islandcn)

> An open-source Dynamic Island-style component for any React app, installed with shadcn. It shows activities like uploads, timers, songs or incoming calls in one island at the top of your app.

- GitHub: https://github.com/opencoredev/islandcn
- GitHub.Locker page: https://github.locker/opencoredev/islandcn
- Stars: 795
- Language: TypeScript
- License: MIT
- Last push: 2026-11-13

## Questions and answers

Written by GitHub.Locker from the README and the repository; check the README below for details.

**Is it a library I import, or a ready-made app?**

It is a component library for your own project, not a standalone app. It has a React-only engine underneath, plus ready presets you can drop in.

**How do I get it into my project?**

Open the playground at /playground, build an island from a preset or a blank activity, and copy the install command and code it generates. Coding agents can also use the optional islandcn-skill registry item.

**What do I need before installing?**

A React project that works with shadcn, since installation goes through it. The README lists no other prerequisites.

**Will the motion match Apple's exact recordings?**

Not from this repo. The recordings the motion was fitted to are not included, so /compare has nothing to show and one test is skipped.

**Can I use it in a commercial product?**

Yes, it is MIT licensed, so you can use it under the terms in the LICENSE file.

**Can I try it before installing anything?**

Yes. The playground at /playground lets you build an island from a preset or a blank activity, fire every action, tune the motion, and see the code.

**What does the engine handle for me?**

An activity stack, four presentations (idle, compact, split, expanded), springs, long-press, alerts and reduced motion support.

**Why does the motion feel close to Apple's island?**

The springs were fitted to frame-by-frame recordings of the real island, so the motion tracks the original closely.


---

## README (checked against GitHub 2026-11-18)

Source: https://github.com/opencoredev/islandcn/blob/main/README.md

# islandcn

A Dynamic Island-style component for any React app, installed with shadcn. Show an upload, a timer, a song, a ride on its way, an incoming call or a recording in one island at the top of your app, and shape each activity around your app's own actions.

```bash
npx shadcn@latest add https://islandcn.dev/r/island-core.json
```

```tsx
"use client";

import { Island, IslandProvider, useIsland } from "@/lib/island";

// Mount once near the root.
<IslandProvider>
  <Island placement="viewport" />
  <App />
</IslandProvider>;

// Then, from any component inside it:
const island = useIsland();
const upload = island.start({
  id: "upload",
  label: "Uploading report.pdf",
  compact: { leading: <CloudIcon />, trailing: <ProgressRing value={0.4} /> },
  expanded: { center: <span>report.pdf</span>, bottom: <Progress value={0.4} /> },
});
upload.update({ compact: { trailing: <ProgressRing value={0.8} /> } });
upload.end();
```

## What's here

- **The engine** (`lib/island/`, registry item `island-core`): the activity stack, four presentations (idle, compact, the split, expanded), springs fitted to frame-by-frame recordings of the real island, long-press, alerts and reduced motion. React only.
- **Presets** (`components/islandcn/`): upload, timer, now playing, incoming call, ride or delivery ETA, recording, nearby transfer, battery and the split, each one file on the engine, plus the content kit they share.
- **The playground** (`/playground`): build an island for your app from a preset or a blank activity, fire every action, tune the motion and copy the install command and the code.
- **The site and docs** (`app/`, `docs/content/`).

Coding agents can use the optional `islandcn-skill` registry item as an install helper; see `/docs/agent-skill`.

## Develop

```bash
pnpm install
pnpm dev           # http://localhost:3000
pnpm typecheck
pnpm build         # builds the registry into public/r, then the site
```

Read `AGENTS.md` before changing anything.

The recordings the motion was fitted to are not in this repo. `/lab` still plays every transition from its built-in sequences in `pnpm dev`; `/compare`, which sets the web side against the recordings, has nothing to show, and the one test that reads them is skipped.

## License

MIT, copyright (c) 2026 Leo. See `LICENSE`. islandcn copies the look and motion of Apple's island, but none of Apple's assets. It is not affiliated with Apple. Dynamic Island is a trademark of Apple Inc.

