@broxus/react-uikit

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