Skip to main content
  • Your opinion matters! Together with you, we want to continuously improve KoliBri. Share your ideas, wishes, or suggestions—quickly and easily.

First steps

For projects at ITZBund, there is a predefined starter repository that can be requested via internal communication channels.

KoliBri is an open-source library for accessible web components, developed by the German Federal Government. The components are framework-independent, compliant with BITV 2.0 and WCAG 2.2, and can be used in almost any web-based project. This page provides a compact overview of how to get started.

⚠️ Prerequisites

  • A modern browser (Chrome, Firefox, Edge, Safari ≥ 16.4).
  • For local development: Node.js (for npx -y serve).

Static example (2 steps)​

The fastest way to try KoliBri is a static HTML file:

Step 1: Create an index.html file:

<!DOCTYPE html>
<html>
<head>
<title>Hello KoliBri!</title>
</head>
<body>
<h1>Hello KoliBri!</h1>
<kol-button _label="Click me" onclick="handleClick()"></kol-button>
<script type="module">
import { register } from "https://unpkg.com/@public-ui/components/dist/index.js";
import { defineCustomElements } from "https://unpkg.com/@public-ui/components/loader/index.mjs";
import { DEFAULT } from "https://unpkg.com/@public-ui/theme-default/dist/index.mjs";

await register(DEFAULT, defineCustomElements);

function handleClick() {
alert("Button clicked!");
}
window.handleClick = handleClick;
</script>
</body>
</html>

Step 2: Start a local server:

npx -y serve

Then open http://localhost:3000 in your browser.

💡 Note: KoliBri uses _.prefixed attributes (e.g., _label) for component properties to avoid conflicts with standard HTML attributes.


Create project from templates​

For framework projects, you can use pre-built templates:

npx degit public-ui/templates/csr/react-vite my-kolibri-app
cd my-kolibri-app
npm i
npm start

Available templates can be found in the .

Register theme​

KoliBri ships components without fixed styling. The visual appearance is determined by a theme passed during registration. The @public-ui/themes package contains several pre-built themes:

ThemeExportDescription
DefaultDEFAULTThe standard theme of KoliBri
BWStBWStFederal Waterways and Shipping Administration;
DesyDesyV11Customs Design System (General Customs Directorate);
ECL (EC)ECL_ECEuropean Commission Design System;
ECL (EU)ECL_EUEuropean Union Design System;
KERNKERN_V2KERN-UX Standard Design System;

Register theme​

The theme is passed as the first parameter when calling register().

import { register } from '@public-ui/components@4.2.1';
import { defineCustomElements } from '@public-ui/components@4.2.1/loader';
import { DEFAULT } from '@public-ui/theme-default';

// Register theme
await register(DEFAULT, defineCustomElements);

💡 Tip: You can easily change the theme by importing the corresponding theme package, e.g.:

import { BWSt } from '@public-ui/theme-bwst';
register(BWSt, defineCustomElements).catch(console.warn);

Available themes: @public-ui/theme-default, @public-ui/theme-bwst, @public-ui/theme-desy, @public-ui/theme-ecl-ec, @public-ui/theme-ecl-eu, @public-ui/theme-kern

Create custom theme​

If none of the provided themes match your corporate design, you can create a custom theme. The approach follows the existing theme structure and is maintained entirely in code.

Use KoliBri with AI Assistants (MCP)​

KoliBri provides a Model Context Protocol (MCP) Server that allows you to access the documentation and components directly in your AI environment (e.g., Cursor, Claude Code, or VS Code with MCP extensions).

🔗 Try the MCP Server

Benefits:

  • Direct access to KoliBri documentation and API.
  • Context-aware help for components, properties, and examples.
  • Integrated into your development environment (e.g., autocompletion, tooltips).

Example: Ask your AI:

"How do I use the kol-button with a custom theme?" → The AI uses the MCP server to provide current and accurate answers from the KoliBri documentation.

Frequently asked questions​

Components are not displayed?

Make sure register() is called before rendering and the promise is resolved.

// ✅ Correct
await register(DEFAULT, defineCustomElements);
// Now render components

// ❌ Wrong
register(DEFAULT, defineCustomElements); // Promise not awaited
// App is rendered immediately - components missing
Which theme should I use?
  • DEFAULT – Neutral default theme (recommended for getting started)
  • ECL_EC / ECL_EU – European Commission / European Union Design System
  • KERN_V2 – KERN-UX Standard Design System
  • An overview of all themes can be found above in the Themes section.
  • Create custom theme
TypeScript errors with properties?

Check:

  1. "moduleResolution": "Node" in tsconfig.json
  2. Framework adapter installed (e.g., @public-ui/react-v19)
  3. Import components from the adapter (not from @public-ui/components)

Next steps: Components​

Once your project is set up and a theme is registered, you can use the KoliBri components. A complete overview of all available components — with examples, properties and events — can be found in the .