# 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](/docs/primitives/). Direct low-level initialization belongs in
[Runtime And Raw HTML](/docs/runtime/).

## 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.

```bash
npm install @starwind-ui/astro
npm install @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.

```bash
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](/docs/getting-started/cli/#primitives).

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

```bash
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.

```bash
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](/docs/getting-started/cli/) for every command and option, or open the
[Primitive API reference](/docs/primitives/) to choose a component.