# Installation

- Page: https://koobiq.io/en/main/installation/overview

This guide describes how to set up an Angular project to use `@koobiq/components`.

## Installing dependencies

Installation using [Angular CLI](https://angular.dev/cli/add) — recommended, because it installs the
Angular packages at the version your application is already on:

```bash
ng add @koobiq/components
```

Manual installation. First install `@angular/cdk` at the version your `package.json` already has for
`@angular/core`:

```bash
npm install @angular/cdk@^21.2.0
```

Then install the library and the rest of its dependencies:

```bash
npm install @koobiq/components overlayscrollbars@2.7.3 @koobiq/icons @koobiq/design-tokens@^4 @koobiq/angular-luxon-adapter @koobiq/luxon-date-adapter @koobiq/date-adapter @koobiq/date-formatter luxon
```

`overlayscrollbars` is pinned to an exact version rather than a range: the scrollbar is built against
that specific release, and this is the version `ng add` installs too. `@koobiq/design-tokens` is held to
major version 4, the one this version of the library is built against.

`@koobiq/angular-luxon-adapter` (or `@koobiq/angular-moment-adapter`) is only needed if you use the
date components — [datepicker](https://koobiq.io/en/components/datepicker.md), [timepicker](https://koobiq.io/en/components/timepicker.md) or
[filter-bar](https://koobiq.io/en/components/filter-bar.md). Either one is a wrapper around a base adapter that has to be
installed next to it — `@koobiq/luxon-date-adapter` or `@koobiq/moment-date-adapter`. npm adds that
base package on its own, Yarn and pnpm do not, so install it explicitly. Install `marked` if you use
[markdown](https://koobiq.io/en/components/markdown.md), `highlight.js` if you use
[code-block](https://koobiq.io/en/components/code-block.md), and `@angular/router` if you use
[breadcrumbs](https://koobiq.io/en/components/breadcrumbs.md).

## Change detection

The components do not need zone.js. They render in a zoneless application, the default since
Angular 21, and keep working in an application that loads zone.js and provides
`provideZoneChangeDetection()`. Nothing has to be configured for them. To make an existing
application zoneless, remove `provideZoneChangeDetection()` from its providers (`ng update` to
Angular 21 adds it to a bootstrap that has no change detection provider) and `zone.js` from its
`polyfills`. `provideZonelessChangeDetection()` only states the default: next to
`provideZoneChangeDetection()` it logs the NG0408 warning, and the order of the providers decides
which one applies.

```typescript
import { provideZonelessChangeDetection } from '@angular/core';

bootstrapApplication(AppComponent, {
    // No provideZoneChangeDetection(); this provider is optional.
    providers: [provideZonelessChangeDetection()]
});
```

## Animations

The components animate with CSS and need no setup: neither `@angular/animations` nor
`provideAnimations()`. The motion is off when the operating system asks for reduced motion
(`prefers-reduced-motion: reduce`). To turn it off in the whole application, for example in an
end-to-end suite, provide `KBQ_ANIMATIONS_CONFIG`:

```typescript
import { KBQ_ANIMATIONS_CONFIG } from '@koobiq/components/core';

bootstrapApplication(AppComponent, {
    providers: [{ provide: KBQ_ANIMATIONS_CONFIG, useValue: { animationsDisabled: true } }]
});
```

## Setting up styles

After installation, you need to include the library styles. Add the following files to the `styles` array in your `angular.json` file:

```json
"styles": [
  "node_modules/@koobiq/icons/fonts/kbq-icons.css",
  "node_modules/@koobiq/design-tokens/web/css-tokens.css",
  "node_modules/@koobiq/design-tokens/web/css-tokens-light.css",
  "node_modules/@koobiq/components/prebuilt-themes/theme.css",
  "src/styles.css"
]
```

`@koobiq/design-tokens` ships code-block, scrollbar and skeleton tokens as opt-in files. With the
default setup you need none of them: their values are already compiled into
`prebuilt-themes/theme.css`. Load the files yourself only if you build the library styles from SCSS
sources:

```scss
@use '@koobiq/design-tokens/web/component-tokens';
@use '@koobiq/design-tokens/web/component-tokens-light';
@use '@koobiq/design-tokens/web/component-tokens-dark';
```

To change the default values, don't load the files — set the CSS variables in your own stylesheet,
see the [theming guide](https://koobiq.io/en/main/theming.md).

## Setting up theme

Add the theme class to the `<body>` element in your `index.html` file:

```html
<body class="kbq-light">
    <app-root></app-root>
</body>
```

For more information about theme setup and switching, see the [theming](https://koobiq.io/en/main/theming.md) section.

## Setting up typography

For proper component rendering, it is recommended to include the [Inter](https://github.com/rsms/inter) font.

For more information, see the [typography](https://koobiq.io/en/main/typography.md) section.

## Using a component

Add a component to your application to verify that everything works correctly.

```typescript
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    imports: [KbqButtonModule, KbqIconModule],
    template: `
        <button kbq-button>
            <i kbq-icon="kbq-plus_16"></i>
            Button
        </button>
    `
})
export class AppComponent {}
```