# UI components

> Configure a UI registry, copy editable component files into your application, and review updates safely.

## Useful when

- You want to install component source that your team can edit.
- Your registry supports multiple frameworks or component destinations.
- You need to update or remove copied component files deliberately.

Use `hulla ui` to copy components from a registry into your app. It installs their source files and dependencies; your app builds from those files without contacting the registry.

## Configure the UI install

Run setup from the project root. The CLI reads sources from `.hulla/ui.json` (or uses its built-in source), detects supported frameworks, and plans file, alias, style, and dependency changes. It shows diffs before replacing existing configuration files.

```sh
hulla ui init
```

Choose the framework and destination paths that match your app. The built-in registry supports Astro, React, and Solid. Other targets need a registry that supplies them.

Setup writes `lib/style.ts` with your chosen class composer. `cn` concatenates classes; `tailwind-merge` also resolves conflicting Tailwind utilities. Rerun `hulla ui init` to change the recorded choice.

> **Tip: Load shared styles on every route**
>
> In Astro, import the installed global stylesheet from a shared layout. The CLI doesn't configure your MDX component map; wire that through the renderer if you use Markdown.

## Add source files

Name the components explicitly so the same operation can be repeated in a script. Add `--framework` when the selected component exists in multiple configured framework targets.

```sh
hulla ui add --framework astro button dialog
```

The command requires one or more component names. It resolves each component's manifest, dependencies, aliases, and copy files. It reports changed file paths; review those diffs and run your app checks. Repeating the command with the same source revision should produce no meaningful source change.

## Update and remove deliberately

To update copied files, select the intended registry tag or commit, rerun `hulla ui init`, then run `hulla ui add` for the components to update. Existing files are updated with visible diffs. See [Configuration](https://hulla.dev/docs/cli/configuration.md) for source settings.

`hulla ui add` can reuse a cached registry without checking whether its remote branch moved. To refresh it:

1. Select the intended source tag or commit in [configuration](https://hulla.dev/docs/cli/configuration.md).
2. Rerun `hulla ui init` to resolve that source.
3. Rerun `hulla ui add` for the components you want to update.
4. If the framework path is still stale, remove only `<cli.cacheDir>/ui.cache.json` and retry.

The default project record is `.hulla/.cache/ui.cache.json`. Downloaded snapshots live separately under `~/.cache/hulla/gittar`; [the downloader's cache policy](https://hulla.dev/docs/gittar/caching.md) explains that layer.

To remove one installed component, name it explicitly. The CLI asks before deleting its component directory; shared support files and dependencies may still serve other components and are retained conservatively.

```sh
hulla ui remove button
```

Inspect the resulting diff and run the application checks. Component removal does not promise to reverse every shared dependency, alias, or stylesheet change created during setup.

With `hulla ui remove --yes`, the deletion confirmation is accepted automatically. Supply the intended component names explicitly in automation.

## Keep the registry out of runtime code

Use a local registry while authoring a private component set, or a pinned remote source for shared consumption. The copied application source is the deliverable; do not import the registry into application code. This lets the app build after the CLI and registry are unavailable.