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 .