Broxus / UIkit

A React component library built on top of React component primitives and adapted to the UIkit CSS framework. Provides a collection of lightweight, composable components and CSS utilities for building web application interfaces.

Components are designed as building blocks — simple and minimal by default, with the expectation that projects apply their own styling and theming via the SCSS customization system.

Table of Contents

• Installation
• Components
  • Layout
  • Navigation
  • Forms & Controls
  • Data Display
  • Typography
  • Feedback
  • Interactive Containers
  • Actions
  • System
• Customization
  • Pre-built CSS
  • SCSS Entry Points
  • Selective Import
  • Overriding SCSS Variables
  • Overriding CSS Custom Properties
  • Hook Mixins
  • Color Mode
• Key Conventions

Installation

Install the package as project dependency

npm install @broxus/react-uikit

yarn add @broxus/react-uikit

pnpm add @broxus/react-uikit

bun add @broxus/react-uikit

Components

Layout

Page structure, spacing, and responsive grid primitives.

| Component | Description | |---|---| | Section | Full-width page section with background variants (default, muted, primary, secondary, tertiary) and size options | | Container | Max-width content wrapper with horizontal padding | | Grid | CSS grid with configurable gaps, dividers, responsive child widths, and equal-height matching | | Flex / Flex.Item | Flexbox container and items with responsive alignment, direction, wrap, and ordering | | Width | Fixed, fractional (1-2, 1-3, etc.), or responsive width control | | Tile | Content tile with background variants, similar to Section but for individual blocks | | Cover | Fills container with an image or video while maintaining aspect ratio | | Align / Align.Left / Align.Center / Align.Right | Horizontal content alignment with RTL support | | Divider | Horizontal or vertical separator line |

Navigation

Menus, tabs, breadcrumbs, and other navigation patterns.

| Component | Description | |---|---| | Navbar | Top navigation bar with .Container, .Left, .Center, .Right, .Nav, .Item, .Toggle | | Nav | Vertical, horizontal, or inline menu with submenus, groups, headers, and dividers | | Subnav | Secondary navigation with divider and pill variants | | Breadcrumb | Hierarchical breadcrumb trail | | Tabs | Tabbed interface (line, card, editable-card) with configurable position and size | | Segmented | Segmented control for switching between 2 or more options | | Dotnav | Dot indicator navigation (e.g. for sliders) | | Iconnav | Icon-based navigation |

Forms & Controls

Input elements, selectors, and form layout.

| Component | Description | |---|---| | Form | Form container with .Label, .Fieldset, .Legend, .Controls — supports stacked and horizontal layouts | | Input | Text input with prefix, suffix, clear button, and validation states | | Input.Number | Numeric input with increment/decrement | | Input.Password | Password input with visibility toggle | | TextArea | Multiline text input with character count | | Select | Dropdown select with single, multiple, and tags modes, search, and loading state | | Checkbox / Checkbox.Group | Checkbox with indeterminate state and group support | | Radio / Radio.Group | Radio button with group support | | Switch | Toggle switch with loading state and custom labels | | Slider | Range slider for numeric value selection | | DatePicker | Date selection with calendar popup and range support |

Data Display

Components for presenting structured content.

| Component | Description | |---|---| | Card | Content card with .Header, .Body, .Footer, .Title, .Badge, .Media — supports style variants and hover effects | | Badge | Small label or count indicator | | Label | Status label with success, warning, danger variants | | List / List.Item | Styled list with marker types (bullet, disc, divider, striped, etc.) and color options | | DescriptionList | Term–description pairs (<dl>) with .Term and .Description | | Progress | Progress bar | | Article | Article content wrapper with .Title and .Meta |

Typography

Text styling and heading components.

| Component | Description | |---|---| | Text | Styled text with color, size, weight, transform, alignment, and wrapping control | | Heading | Section heading with size scale and decorations (bullet, divider, line) | | Link | Styled link with variants (heading, muted, reset, text, toggle) |

Feedback

Notifications, dialogs, and loading indicators.

| Component | Description | |---|---| | Alert | Notification message with severity levels (primary, success, warning, danger) and close animation | | Modal | Dialog window with centered, full-screen, and custom container options | | Drawer | Side panel with push, reveal, and slide animations | | Spinner | SVG loading spinner with configurable size | | Overlay | Content overlay with positioning options |

Interactive Containers

Expandable, collapsible, and popup containers.

| Component | Description | |---|---| | Accordion / Accordion.Item | Collapsible content panels | | Drop | Popup overlay attached to a trigger element, with placement and arrow options | | Dropdown | Dropdown menu (wraps Drop) |

Actions

Buttons and action triggers.

| Component | Description | |---|---| | Button / Button.Group | Action button with variants (primary, secondary, tertiary, danger, link, text), sizes, and shapes (circle, round) | | Close | Close button (X icon) |

System

Configuration providers and base utilities.

| Component | Description | |---|---| | ConfigProvider | Global configuration for component defaults: icons, locale, breakpoints, direction, popup containers | | Inverse | Color mode provider for light/dark theme switching with persistence | | Icon | Icon from the built-in icon set |

Customization

The library provides two ways to consume styles:

• Pre-built CSS — ready-to-use stylesheets available at @broxus/react-uikit/assets/*.css, no SCSS toolchain needed (see Pre-built CSS)
• SCSS source — full customization via variables, tokens, and hook mixins

The SCSS styling system has two layers:

• SCSS variables (compile-time) — used for computations (color.scale(), rgba(), math) and resolved to literal values at build
• CSS custom properties (runtime) — the actual design tokens consumed by components via var(--...)

Pre-built CSS

Pre-compiled CSS assets available without an SCSS toolchain:

| Asset | Purpose | |---|---| | @broxus/react-uikit/assets/uikit.min.css | Fully compiled CSS with default component set | | @broxus/react-uikit/assets/vars.css | Global (--global-*) and base (--base-*) CSS custom properties. Component-specific tokens are included in their respective modules | | @broxus/react-uikit/assets/custom-media.css | PostCSS custom media queries for breakpoints |

Components can also be imported individually:

@import '@broxus/react-uikit/assets/button.css';
@import '@broxus/react-uikit/assets/card.css';
@import '@broxus/react-uikit/assets/modal.css';

Module names correspond to component names in the component map.

[!WARNING] Important

Component styles use custom media queries for responsive breakpoints (@media (--media-breakpoint-small), etc.). These are not natively supported by browsers and require PostCSS with postcss-custom-media plugin to be processed. Import @broxus/react-uikit/assets/custom-media.css to provide the breakpoint definitions.

SCSS Entry Points

| Entry point | Purpose | |---|---| | @broxus/react-uikit/styles/import | Main entry — outputs component styles with conditional token generation | | @broxus/react-uikit/styles/vars | Outputs only :root CSS custom properties (tokens), no component styles | | @broxus/react-uikit/styles/tokens | Re-exports token mixins (button-tokens, card-tokens, etc.) for selective inclusion | | @broxus/react-uikit/styles/variables | SCSS variable defaults — override via @forward ... with (...) | | @broxus/react-uikit/styles/components | Re-exports component style mixins and inverse style mixins |

Selective Import

Include only the components you need to reduce CSS output:

@use '@broxus/react-uikit/styles/import' with (
    $components: (button: true, card: true, control: true, modal: true),
);

Or include everything:

@use '@broxus/react-uikit/styles/import' with (
    $components: (all: true),
);

Component map:

| Group | Enabled by default | Disabled by default | |---|---|---| | Base | base | — | | Elements | link, heading, divider, list, icon, form, control, input-password, input-number, checkbox, radio, datepicker, button, slider, switch, select, textarea | description-list, progress | | Layout | section, container, grid, tile, card | — | | Common | close, spinner, alert, badge, label, tooltip | totop, marker, overlay, article, search, placeholder | | Interaction | accordion, drop, dropdown, modal, drawer | sticky, leader | | Navigation | nav, navbar, subnav, segmented, breadcrumb, tabs | dotnav, thumbnav, iconnav | | Utilities | animation, motion, width, height, text, align, svg, utility, flex, margin, padding, position, transition, visibility | column, cover, background, inverse |

Overriding SCSS Variables

Override library defaults by forwarding with new values:

@forward '@broxus/react-uikit/styles/variables' with (
    $global-font-family: 'Inter', sans-serif !default,
    $global-primary-color: #ad6d60 !default,
    $global-background: #0d0d0d !default,
    $global-border-radius: 8px !default,
    $button-primary-hover-background: color.scale(#ad6d60, $lightness: -8%) !default,
);

Overriding CSS Custom Properties

Token mixins accept @content blocks to override specific CSS custom properties:

@use '@broxus/react-uikit/styles/tokens';

:root {
    @include tokens.global-tokens {
        --global-primary-color: #ad6d60;
        --global-background: #0d0d0d;
    }
    @include tokens.button-tokens {
        --button-round-border-radius: var(--global-small-border-radius);
        --button-disabled-background: rgba(173, 109, 96, 6%);
    }
    // Components without overrides — just include with defaults:
    @include tokens.card-tokens;
    @include tokens.alert-tokens;
}

Hook Mixins

Inject custom CSS into component render points. Define mixins and register them via the $mixins map:

// _mixins.scss
@mixin hook-button() {
    font-weight: 500;
    transition: background-color 200ms ease-in-out, color 200ms ease-in-out;
}

// index.scss
@use 'sass:meta';
@use 'mixins';

@use '@broxus/react-uikit/styles/import' as * with (
    $components: (all: true),
    $mixins: (
        'hook-button': meta.get-mixin('hook-button', 'mixins'),
    ),
);

Hook naming convention: hook-{component}, hook-{component}-{modifier}, hook-{component}-{state}, hook-{component}-misc, hook-inverse-{component}.

Color Mode

The $*-color-mode variables control text color direction, not the theme itself:

• light — light text on dark background
• dark — dark text on light background

@forward '@broxus/react-uikit/styles/variables' with (
    $section-default-color-mode: light,   // dark background, light text
    $section-primary-color-mode: dark,    // primary background, dark text
    $card-primary-color-mode: dark,
    $navbar-color-mode: light,
);

Key Conventions

• Compound components — complex components use dot-notation: Card.Header, Flex.Item, Nav.Sub, etc.
• Responsive breakpoints — layout and typography components support s, m, l, xl breakpoint configs
• Standard sizes — xsmall | small | medium | large | xlarge
• Form states — success | warning | danger | blank
• RTL support — all components support direction prop or global config via ConfigProvider
• Selective import — SCSS entry points accept a $components map to include only needed component styles