Install Sora UI in a Next.js or Vite project using the shadcn CLI — dependencies, Tailwind config, folder structure in 3 steps — plus fixes for common install errors.
Note: We use installation process as shadcn/ui.
Initialize shadcn/ui
Run the init command to create a new project with shadcn/ui or setup an existing one. This sets up Tailwind, CSS variables, and the @/ import alias that every Sora UI component (and both install methods below) depends on — it's required either way.
Add components
Two ways to pull components in from here — pick whichever fits your workflow.
sora-cli —
skips registering the @soralabs scope, defaults straight to the Sora UI
registry:
Or browse components interactively: npx @soralabs/cli@latest add
Or, using the shadcn CLI directly — register the @soralabs scope once (Sora UI is listed in the official shadcn registry index):
Then install primitives with the @soralabs scope. Browse the blocks in Motion or list every item:
Only if the shadcn CLI errors — for example unknown registry, cannot
resolve @soralabs, or fetch timeout — see The CLI does not recognize
@soralabs for the manual
components.json fix.
Project structure
After shadcn init, registering @soralabs, and adding a primitive, your app typically looks like this. Highlighted files are created or updated by the CLI.
Troubleshooting
Verify your versions
| Dependency | Minimum recommended version |
|---|---|
| Motion | ≥ 12.23.0 |
| React | ≥ 19 |
| Tailwind CSS | ≥ 4.1.0 |
| Base UI | 1.0.0-beta.3 |
| Radix UI | ≥ 1.4.0 |
| Headless UI | ≥ 2.2.0 |
Make sure your environment meets or exceeds these versions to ensure Sora UI remains compatible and stable.
Documentation display issues
Certain browser extensions can interfere with how the documentation is rendered. Common culprits include:
If problems persist after disabling extensions, clear your browser cache and refresh the page.
The CLI does not recognize @soralabs
Sora UI is listed in the official shadcn registry index. Register the namespace first:
If that still fails, add or update the registries field in components.json:
If you were testing against a local docs server (http://localhost:3000/r/{name}.json), switch back to the production URL when:
- The dev server is not running
shadcn listorshadcn addtimes out or returns 404- You are installing into a project outside this monorepo
Verify the registry is reachable:
Then install with the scope, for example:
A Sora dependency resolves from ui.shadcn.com
If shadcn add @soralabs/accordion fails with a 404 for something like hooks-use-auto-height on ui.shadcn.com, the published registry item listed that dependency without the @soralabs/ scope. Sora-only deps must be scoped so the CLI fetches them from your @soralabs registry URL, not the default shadcn registry.
Ensure components.json includes the Sora registry (see above), then retry after the registry on https://ui.soralabs.studio/r/ is updated. For local testing, point @soralabs at http://localhost:3000/r/{name}.json while bun dev is running in this repo.
The CLI installation does not respect aliases
In some projects, components may not install in the desired location that you configured in the aliases in the components.json file. This is because we can't use a target path with aliases.
We have filed an issue on shadcn/ui, Shadcn added it to the roadmap.
For now, we recommend using the manual installation.
Flickering with the highlight component
If you are experiencing flickering issues with the Highlight component, this is likely due to React's strict mode. Set it to false to avoid issues during development.
Other issues
If you encounter any other problem, see the Community page — open an issue or ask in Discussions.
Introduction
What Sora UI is, how the copy-paste component model works, AI & MCP support, and why it's built for React, Motion, GSAP, and Tailwind CSS.
Changelog
Latest updates, weekly releases, and announcements.
Built by Axyl. A motion-first component registry for React.
Last updated: 10/30/2026