1. Install

   In a project that already uses shadcn/ui, add the registry once, then the component.

   pnpmnpmyarnbun

   pnpm dlx shadcn@latest registry add @kinematic=https://kinematic.design/r/{name}.json

   pnpmnpmyarnbun

   pnpm dlx shadcn@latest add @kinematic/activity

2. Add the viewport

   Render it once, near the root of your app. It's where every activity appears.

   import { ActivityViewport } from "@/components/ui/activity"
   
   export default function RootLayout({ children }) {
     return (
       <html lang="en">
         <body>
           {children}
           <ActivityViewport layout="single" />
         </body>
       </html>
     )
   }

3. Start one

   Call it from anywhere, even outside React.

   import { activity } from "@/components/ui/activity"
   
   activity.track({
     title: `Uploading ${files.length} files`,
     items: files.map((file) => ({
       id: file.name,
       label: file.name,
       run: (progress) => upload(file, { onProgress: progress }),
     })),
     outcome: () => ({ label: "Files ready", action: { label: "Open", onClick: openFiles } }),
   })

That's it. Click the pill to open it. From here, Activity covers the other kinds and how to build your own.