> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# Using components

> Add and use components from the Helios registry

Learn how to discover, install, and use components from the Helios component registry.

## Prerequisites

Before adding components, initialize your project:

```bash theme={null}
helios init
```

This creates a `helios.config.json` file in your project root.

## Browsing components

List all available components:

```bash theme={null}
helios components
```

Search for specific components:

```bash theme={null}
helios components timer
```

Filter by framework:

```bash theme={null}
helios components --framework react
```

Show components for all frameworks:

```bash theme={null}
helios components --all
```

## Adding components

<Steps>
  <Step title="Install a component">
    Run the add command with the component name:

    ```bash theme={null}
    helios add timer
    ```

    This will:

    * Fetch the component from the registry
    * Resolve and install registry dependencies (like `use-video-frame`)
    * Copy files to your `src/components/helios` directory
    * Install npm dependencies
    * Update `helios.config.json`
  </Step>

  <Step title="Review installed files">
    Check your components directory:

    ```
    src/components/helios/
    ├── Timer.tsx
    └── useVideoFrame.ts
    ```

    The timer component depends on `use-video-frame`, so both were installed.
  </Step>

  <Step title="Import and use">
    Import the component in your code:

    ```tsx theme={null}
    import { Timer } from './components/helios/Timer';

    function MyVideo({ helios }) {
      return (
        <div>
          <Timer helios={helios} />
        </div>
      );
    }
    ```
  </Step>
</Steps>

## Skip dependency installation

If you want to manage dependencies yourself:

```bash theme={null}
helios add timer --no-install
```

The component files will be copied, but npm packages won't be installed automatically.

## Dependency resolution

Components can depend on:

1. **npm dependencies** - External packages (e.g., `react`, `@helios-project/core`)
2. **Registry dependencies** - Other components in the registry (e.g., `use-video-frame`)

The CLI automatically resolves the entire dependency tree. If component A depends on component B, both are installed when you run `helios add A`.

## Framework detection

The CLI reads your `framework` setting from `helios.config.json`:

```json theme={null}
{
  "framework": "react"
}
```

When adding components, it prioritizes:

1. Exact framework match (e.g., `react`)
2. Vanilla/framework-agnostic components
3. Falls back if no match found

## Configuration file

After adding components, `helios.config.json` tracks what's installed:

```json theme={null}
{
  "version": "1.0.0",
  "directories": {
    "components": "src/components/helios",
    "lib": "src/lib"
  },
  "framework": "react",
  "components": ["use-video-frame", "timer"],
  "dependencies": {
    "use-video-frame": "latest",
    "timer": "latest"
  }
}
```

## Modifying components

Once copied, components belong to you. Edit them directly:

* Change styles
* Add props
* Remove unused features
* Combine multiple components

No need to fork or submit PRs - you own the code.

## Updating components

Re-running `helios add <component>` will skip existing files by default. To overwrite:

```bash theme={null}
# Manually delete and re-add
rm src/components/helios/Timer.tsx
helios add timer
```

<Note>
  Currently, there's no automatic update mechanism. You own the code, so updates are manual.
</Note>