> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliosrender.com/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

**1. 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`

**2. 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.

**3. 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>
  );
}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.