First steps

Create a new project

A new project can be created quickly using the command line wizard.

npm init kolibri@latest my-kolibri-app

Integration into existing projects

Embedding fonts

Fonts are loaded by nature detached from the CSS and must be included in the frame page (HTML file) depending on the KoliBri theme (style guide).

For this purpose, the fonts supplied in the library can be copied into your own assets.

Please check which files You need and only import those to minimize traffic.

<!DOCTYPE html>
<html lang="de" dir="ltr">
 <head>
  <title>Webapplication | KoliBri</title>
  <meta charset="UTF-8" />
  <meta name="description" content="..." />
  <base href="/" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <link rel="shortcut icon" type="image/x-icon" href="assets/kolibri.ico" />
  <link rel="stylesheet" href="assets/bundes/style.css" />
  <link rel="stylesheet" href="assets/codicons/codicon.css" />
  <link rel="stylesheet" href="assets/fontawesome-free/css/all.min.css" />
  <link rel="stylesheet" href="assets/icofont/icofont.min.css" />
  <link rel="stylesheet" href="assets/noto-sans/noto-sans.css" />
  <link rel="stylesheet" href="assets/kreon/style.css" />
  <link rel="stylesheet" href="assets/material-icons/iconfont/material-icons.css" />
  <link rel="stylesheet" href="assets/material-symbols/index.css" />
  <link rel="stylesheet" href="assets/roboto/roboto.css" />
  <link rel="stylesheet" href="assets/tabler-icons/tabler-icons.css" />
 </head>
</html>

Typescript

To get full code completion, add these lines to tsconfig.json:

{
 "compilerOptions": {
  ...
 "moduleResolution": "Node",
  ...
 },
 ...
}

I Vite + React

1. Installing the KoliBri libraries

npm i @public-ui/components @public-ui/themes @public-ui/react

pnpm i @public-ui/components @public-ui/themes @public-ui/react

yarn add @public-ui/components @public-ui/themes @public-ui/react

2. Integration

main.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.tsx";
import "./index.css";

+import { register } from "@public-ui/components";
+import { defineCustomElements } from "@public-ui/components/dist/loader";
+import { DEFAULT } from "@public-ui/themes";

+register(DEFAULT, defineCustomElements)
+ .then(() => {
  ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
  <App />
  </React.StrictMode>
  );
+ })
+ .catch(console.warn);

3. Include modules

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
  <meta charset="UTF-8" />
  <link rel="icon" type="image/svg+xml" href="/vite.svg" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Vite + React + TS</title>
+ <script type="module" src="/node_modules/@public-ui/components/dist/kolibri/kolibri.esm.js"></script>
  </head>
  <body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

4. Example

import React from 'react';
import { KolSpin } from '@public-ui/react';

export const AppComponent = () => {
 return (
  <div>
   <KolSpin _show />
  </div>
 );
};

II Vite + Vue

1. Installing the KoliBri libraries

npm i @public-ui/components @public-ui/themes @public-ui/vue

pnpm i @public-ui/components @public-ui/themes @public-ui/vue

yarn add @public-ui/components @public-ui/themes @public-ui/vue

2. Plugin

kolibri.plugin.ts

import type { Plugin } from 'vue';
import { defineCustomElements } from '@public-ui/components/dist/loader';
import { register } from '@public-ui/components';
import { ITZBund } from '@public-ui/themes';
export const ComponentLibrary: Plugin = {
 install() {
  register(ITZBund, defineCustomElements)
   .then(() => console.log('Components registered'))
   .catch(console.warn);
 },
};

main.ts:

import { createApp } from 'vue'
import App from './App.vue'
import './assets/main.css'
+ import { ComponentLibrary } from './vue.plugin'

const app = createApp(App)

+ app.use(ComponentLibrary)

app.mount('#app')

3. Integrate modules

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
  <meta charset="UTF-8" />
  <link rel="icon" href="/favicon.ico" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <script type="module" src="/node_modules/@public-ui/components/dist/kolibri/kolibri.esm.js"></script>
  <title>Vite + Vue + TS</title>
  </head>
  <body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
  </body>
</html>

4. Customise configuration

vite.config.ts

import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vitejs.dev/config/
export default defineConfig({
- plugins: [],
+ plugins: [
+ vue({
+ template: {
+ compilerOptions: {
+ // treat all tags with a dash as custom elements
+ isCustomElement: (tag) => tag.includes('-')
+ }
+ }
+ })
+ ],
  resolve: {
  alias: {
  '@': fileURLToPath(new URL('./src', import.meta.url))
  }
  }
})

5. Example

<KolInputText :_value="text" :_on="{ onChange: (e: unknown, v: string) => (text = v) }"></KolInputText>
<KolButton _label="Text löschen" :_on="{ onClick: () => (text = '') }"></KolButton>

Note: KoliBri inputs usually pass the original event as the first parameter and the value of the field as the second.

III React

1. Installing the KoliBri libraries

npm i @public-ui/components @public-ui/themes @public-ui/react

pnpm i @public-ui/components @public-ui/themes @public-ui/react

yarn add @public-ui/components @public-ui/themes @public-ui/react

2. Registering the KoliBri loader

After the preparations are completed, only the KoliBri loader has to be registered. It ensures that the Web Components are reloaded asynchronously (lazy) as soon as they are used in the web page.

Method	Description
register	Sets a theme and then registers the loader
DEFAULT	Registers the loader for e.g. the DEFAULT theme
defineCustomElements	Registers the Loader for the Web Components

3. Integration

import React from 'react';
import ReactDOM from 'react-dom';

import { AppComponent } from './components/app/component';

import { register } from '@public-ui/core';
import { defineCustomElements } from '@public-ui/components/dist/loader';
import { DEFAULT } from '@public-ui/themes';

register(DEFAULT, defineCustomElements)
 .then(() => {
  const htmlDivElement: HTMLDivElement | null = document.querySelector<HTMLDivElement>('div#app');
  if (htmlDivElement instanceof HTMLDivElement) {
   const root = createRoot(htmlDivElement);
   root.render(<AppComponent />);
  }
 })
 .catch(console.warn);

4. Example

import React from 'react';
import { KolSpin } from '@public-ui/react';

export const AppComponent = () => {
 return (
  <div>
   <KolSpin _show />
  </div>
 );
};

IV Without any framework

npm i @public-ui/components @public-ui/themes

pnpm i @public-ui/components @public-ui/themes

yarn add @public-ui/components @public-ui/themes

<!DOCTYPE html>
<html lang="en">
  <head>
  <meta charset="UTF-8" />
  <link rel="icon" type="image/svg+xml" href="/vite.svg" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Title</title>
+ <script type="module" src="/node_modules/@public-ui/components/dist/kolibri/kolibri.esm.js"></script>
  </head>
  <body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
  </body>
</html>

To get code completion it may be necessary to create .vscode/settings.json and insert the following:

{
 "html.customData": ["./node_modules/@public-ui/components/vscode-custom-data.json"]
}

Here the web component notation (kebab-case) is to be used. (e.g.: <kol-heading>)

V Static website

To include KoliBri in a static web page you only have to include the following script tag. If fonts and/or icons are used, they must be included as described above.

<script type="module">
 import { register } from 'https://unpkg.com/@public-ui/components/dist/esm/index.js';
 import { defineCustomElements } from 'https://unpkg.com/@public-ui/components/dist/loader/index.js';
 import { ITZBund } from 'https://unpkg.com/@public-ui/themes/dist/index.mjs';
 register(ITZBund, defineCustomElements).catch(console.warn);
</script>

Here the web component notation (kebab-case) is to be used. (e.g.: <kol-heading>)

Additional features

Developer Tools

By means of the following configuration in the HTML file the developer tools of KoliBri can be activated.

…
<html>
 <head>
  <meta name="kolibri" content="dev-mode=true" />
 </head>
 …
</html>

Experimental mode

By means of the following configuration in the HTML file the experimental mode can be activated.

…
<html>
 <head>
  <meta name="kolibri" content="experimental-mode=true" />
 </head>
 …
</html>

Color contrast analysis

To detect color contrast errors within the DOM, you can enable color contrast analysis using the following configuration.

…
<html>
 <head>
  <meta name="kolibri" content="color-constrast-analysis=true" />
 </head>
 …
</html>

3. Registering the component loaders

After the preparations are complete, only the component loader needs to be registered. It ensures that the Web Components are reloaded asychronously (lazy) as soon as they are used in the web page.

Method	Description
register	Sets a theme and then registers the loader
BMF	Registers the loader for e.g. the BMF theme
defineCustomElements	Registers the loader for the Web Components

Variant A: Static project

<head>
 <script type="module">
  import { register } from 'https://unpkg.com/@public-ui/components@1.4.0-rc.6';
  import { defineCustomElements } from 'https://unpkg.com/@public-ui/components@1.4.0-rc.6/dist/loader';
  import { BMF } from 'https://unpkg.com/@public-ui/themes@1.4.0-rc.6';
  register([BMF], defineCustomElements)
   .then(() => {})
   .catch(console.warn);
 </script>
</head>
<body>
 <kol-spin _show>
</body>

Variant B: React project

Integration

import React from 'react';
import ReactDOM from 'react-dom';

import { AppComponent } from './components/app/component';

import { register } from '@public-ui/components';
import { defineCustomElements } from '@public-ui/components/dist/loader';
import { BMF } from '@public-ui/themes';

register(BMF, defineCustomElements)
 .then(() => {
  const htmlDivElement: HTMLDivElement | null = document.querySelector<HTMLDivElement>('div#app');
  if (htmlDivElement instanceof HTMLDivElement) {
   const root = createRoot(htmlDivElement);
   root.render(<AppComponent />);
  }
 })
 .catch(console.warn);

Install adapter

An adapter is available for React that allows seamless and typed usage in TSX.

NPM npm i @public-ui/react or

PNPM pnpm i @public-ui/react or

YARN yarn add @public-ui/react

Use component

import React, { FunctionComponent } from 'react';
import { KolSpin } from '@public-ui/react';

export const App: FunctionComponent = () => <KolSpin _show />;

Special features

Developer tools

By using the following configuration in the HTML file the developer tools of KoliBri can be activated.

…
<html>
 <head>
  <meta name="kolibri" content="dev-mode=true" />
  <!-- <meta name="kolibri" content="dev-mode=true,experimental-mode=true" /> -->
 </head>
 …
</html>

Experimental mode / lab

By using the following configuration in the HTML file the experimental mode can be activated.

…
<html>
 <head>
  <meta name="kolibri" content="experimental-mode=true" />
 </head>
 …
</html>

Color-Contrast-Analysis

The color contrast analysis allows detecting color contrast errors within the DOM. By adding the following configuration to the meta tag, the color contrast analysis is enabled.

…
<html>
 <head>
  <meta name="kolibri" content="color-constrast-analysis=true" />
 </head>
 …
</html>

Create a new project​

Integration into existing projects​

Embedding fonts​

Typescript​

I Vite + React​

1. Installing the KoliBri libraries​

2. Integration​

3. Include modules​

4. Example​

II Vite + Vue​

1. Installing the KoliBri libraries​

2. Plugin​

3. Integrate modules​

4. Customise configuration​

5. Example​

III React​

1. Installing the KoliBri libraries​

2. Registering the KoliBri loader​

3. Integration​

4. Example​

IV Without any framework​

V Static website​

Additional features​

Developer Tools​

Experimental mode​

Color contrast analysis​

3. Registering the component loaders​

Variant A: Static project​

Variant B: React project​

Integration​

Install adapter​

Use component​

Special features​

Developer tools​

Experimental mode / lab​

Color-Contrast-Analysis​

Create a new project

Integration into existing projects

Embedding fonts

Typescript

I Vite + React

1. Installing the KoliBri libraries

2. Integration

3. Include modules

4. Example

II Vite + Vue

1. Installing the KoliBri libraries

2. Plugin

3. Integrate modules

4. Customise configuration

5. Example

III React

1. Installing the KoliBri libraries

2. Registering the KoliBri loader

3. Integration

4. Example

IV Without any framework

V Static website

Additional features

Developer Tools

Experimental mode

Color contrast analysis

3. Registering the component loaders

Variant A: Static project

Variant B: React project

Integration

Install adapter

Use component

Special features

Developer tools

Experimental mode / lab

Color-Contrast-Analysis