On this page

Primitives

Primitives provide Runtime-backed behavior and anatomy without Starwind’s styled wrapper. Most projects should begin with a styled component and use a Primitive only when they need to own the markup, styling, or adapter source at a lower layer.

Choose a Layer

Approach	Use it when
Styled component	You want ready-to-render Starwind UI with editable application source.
Primitive package	You want framework-native anatomy and behavior while keeping the adapter as a dependency.
Vendored Primitive source	You need to modify and own the framework adapter source in your project.
Runtime and raw HTML	You render your own DOM contract or are building a custom integration.

The behavior-first reference for individual components remains in the Primitive API section. Direct low-level initialization belongs in Runtime And Raw HTML.

Import Primitive Packages

starwind init installs the adapter for the project’s primary framework, so initialized projects usually need no additional package command. Install an adapter directly when the project was set up manually or when you need the other framework package as well.

pnpm add @starwind-ui/astro
pnpm add @starwind-ui/react

npm install @starwind-ui/astro
npm install @starwind-ui/react

yarn add @starwind-ui/astro
yarn add @starwind-ui/react

Import only the package matching the file you are authoring. Primitive API pages show the available parts, props, Runtime links, and framework-specific examples.

Vendor Primitive Source

Vendoring copies compile-ready adapter source into the project. You own those files after they are written, including any changes you make. The CLI tracks the installed Primitive versions so it can plan later updates.

starwind primitives add button
starwind primitives update button
starwind primitives list

Use update --dry-run, --diff, or --view before accepting an update when you have modified vendored files. The complete options belong in the CLI primitives reference.

Framework Targeting

Without an override, Primitive commands use the primary framework from starwind.config.json. Target Astro or React explicitly when a project contains both:

starwind primitives add button --framework react
starwind primitives list --framework all

The primary framework uses primitiveDir, which defaults to src/components/starwind-primitives. Additional frameworks use primitiveDirs.<framework> and default to a framework-specific directory such as src/components/starwind-react-primitives.

Custom Destinations

Use --to <dir> when vendored source should live somewhere other than the configured destination. The CLI records the selected location for future operations.

starwind primitives add button --to src/primitives
starwind primitives add button --framework react --to src/react-primitives

Keep imports pointed at the vendored directory you selected. When you only need package imports, do not vendor the same Primitive unless you intentionally want to maintain a local fork.

Ownership and Updates

Package imports receive adapter changes through normal dependency updates.
Vendored source changes only when you run a Primitive update command.
Review vendored updates like application code because they may overwrite local modifications.
Runtime internals remain package dependencies; Primitive vendoring does not copy Runtime source.

See the CLI reference for every command and option, or open the Primitive API reference to choose a component.