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

Installing dependencies

Installation using Angular CLI — recommended, because it installs the Angular packages at the version your application is already on:

ng add @koobiq/components

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

npm install @angular/cdk@^21.2.0

Then install the library and the rest of its dependencies:

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, timepicker or filter-bar. 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, highlight.js if you use code-block, and @angular/router if you use breadcrumbs.

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.

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:

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:

"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:

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

Setting up theme

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

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

For more information about theme setup and switching, see the theming section.

Setting up typography

For proper component rendering, it is recommended to include the Inter font.

For more information, see the typography section.

Using a component

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

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 {}