Sora UI

Installation

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.

pnpm dlx shadcn@latest init

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:

pnpm dlx @soralabs/cli@latest add text-effect

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):

pnpm dlx shadcn@latest registry add @soralabs

Then install primitives with the @soralabs scope. Browse the blocks in Motion or list every item:

pnpm dlx shadcn@latest add @soralabs/text-effect

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.

Import Components

Import the component to your project.

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.

page.tsx
text-effect.tsx
utils.ts
components.json

Troubleshooting

Verify your versions

DependencyMinimum recommended version
Motion≥ 12.23.0
React≥ 19
Tailwind CSS≥ 4.1.0
Base UI1.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 list or shadcn add times 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.

Built by Axyl. A motion-first component registry for React.

Last updated: 10/30/2026