# Registering KoliBri Components and Themes
KoliBri Web Components ship without side effects so that you can decide _when_ and _how_ to load them.
Every runtime—vanilla JavaScript, React, Angular, Vue, etc.—must explicitly register the component set **and** at least one theme before rendering any `<kol-*>` tag. The Model Context Protocol (MCP) server exposes this guide under the concept identifier `docs/HOWTO_REGISTER_COMPONENTS_AND_THEMES` so KI agents can retrieve the exact steps.
## 1. Install the packages you need
Install the component bundle plus the theme (or themes) you want to offer to your users:
```bash
pnpm add @public-ui/components @public-ui/theme-default
```
> ℹ️ Replace `@public-ui/theme-default` with another theme package (e.g. `@public-ui/theme-ecl`) if you prefer a different look.
## 2. Call `register` during application bootstrap
```ts
import { register } from '@public-ui/components';
import { defineCustomElements } from '@public-ui/components/loader';
import { DEFAULT } from '@public-ui/theme-default';
await register(DEFAULT, defineCustomElements);
```
- `register` wires up the custom elements and installs the provided theme(s).
- `defineCustomElements` is generated by Stencil and registers the underlying HTML custom elements. Pass an empty array (`[]`) if your framework adapter handles element definition for you.
- Awaiting the promise ensures the registry is ready before you render components.
## 3. Register multiple themes (optional)
You can pass an array when you want to ship several themes at once:
```ts
import { register } from '@public-ui/components';
import { defineCustomElements } from '@public-ui/components/loader';
import { DEFAULT } from '@public-ui/theme-default';
import { ECL } from '@public-ui/theme-ecl';
await register([DEFAULT, ECL], defineCustomElements);
```
Switching themes at runtime works through the `kol-theme` attribute—no additional registration call is required.
## 4. Framework-specific notes
- **React / Solid / Svelte / Vue**: Use the official adapters (`@public-ui/react`, `@public-ui/solid`, `@public-ui/svelte`, `@public-ui/vue`). They wrap `register` for you, but you still need to call it once in your app entry point before rendering.
- **Angular**: Install `@public-ui/angular` and follow the schematic. It invokes `register` during the Angular bootstrapping phase.
- **Static HTML / plain JS**: Load the ESM bundles from a CDN and call `register` with `defineCustomElements` inside a `<script type="module">` block.
## 5. Troubleshooting
- **`<kol-button>` renders as plain text** \
Components were not registered. Call `register(...)` before rendering or ensure the promise resolved.
- **Components use fallback styling** \
No theme was registered. Pass a theme object (e.g. `DEFAULT`) to `register`.
- **Duplicate custom element definition error** \
`defineCustomElements` executed twice. Call `register` only once per page load or pass `[]` when an adapter already defines the elements.
## 6. Quick reference for KI agents
1. Install `@public-ui/components` + at least one theme package.
2. Import `register` from `@public-ui/components`.
3. Import `defineCustomElements` unless your integration takes care of it.
4. Pass a theme (or an array of themes) and the element loader to `register`.
5. Await the promise before rendering `<kol-*>` components.
Keep this checklist handy; the MCP endpoint will always return the latest version of this guide.
