Introduction

Webui is a lightweight, framework-agnostic UI library designed for modern web applications. It provides a consistent set of components, utilities, and design tokens that work seamlessly across React, Vue, Svelte, and vanilla JavaScript.

ℹ️ Note: Webui v2.x requires Node.js 18+ and modern browser support. Check our migration guide if you're upgrading from v1.x.

Key Features

Framework Agnostic: Write once, render everywhere. Core components don't depend on any UI framework.
Tree-shakeable: Only bundle what you use. Our ES module structure ensures optimal bundle size.
Accessible: WCAG 2.1 AA compliant out of the box with proper ARIA attributes and keyboard navigation.
Customizable: CSS variables and design tokens make theming effortless.

Installation

Install Webui using your preferred package manager:

npm install @webui/core @webui/components

Or with Yarn:

yarn add @webui/core @webui/components

For CDN usage in vanilla projects:

<script src="https://cdn.webui.io/v2.4.0/webui.min.js"></script>

✅ Recommended: For production applications, we recommend using npm or Yarn to leverage package manager caching and dependency resolution.

Configuration

Webui can be configured globally through a configuration file or directly in your application entry point. Configuration must be initialized before rendering any components.

Global Config

import { Webui } from '@webui/core';

Webui.configure({
  theme: 'light',
  breakpoints: { sm: '640px', md: '768px', lg: '1024px', xl: '1280px' },
  animations: { enabled: true, duration: '200ms', easing: 'cubic-bezier(0.4, 0, 0.2, 1)' },
  accessibility: { reducedMotion: false, focusVisible: true }
});

⚠️ Warning: Configuration must be initialized before rendering any components. Otherwise, default values will be applied and hot-reloading may cause inconsistent states.

Environment Variables

Variable	Type	Default	Description
`WEBUI_DEV_MODE`	boolean	`false`	Enables development warnings and performance tracking
`WEBUI_LOCALE`	string	`en-US`	Default locale for date/number formatting
`WEBUI_DEBUG`	boolean	`false`	Prints detailed logs for component mounting

Buttons

The Button component provides a flexible way to trigger actions. It supports multiple variants, sizes, and states while maintaining consistent accessibility standards.

<Webui.Button variant="primary" size="lg" disabled>
  Submit Form
</Webui.Button>

<Webui.Button variant="outline" icon="arrow-right" onClick={handleNext}>
  Continue
</Webui.Button>

Props

Prop	Type	Default	Description
`variant`	string	`default`	Visual style: primary, secondary, outline, ghost, danger
`size`	string	`md`	Size: sm, md, lg
`disabled`	boolean	`false`	Disables interaction and applies visual state
`loading`	boolean	`false`	Shows spinner and disables clicks
`icon`	string	-	Icon name from the webui icon set

Hooks & Utilities

Webui provides utility hooks for managing state, events, and theme across your application. These are framework-agnostic and work with any reactive system.

useTheme

import { useTheme } from '@webui/core';

const { theme, setTheme, isDark } = useTheme();

// Toggle theme
setTheme('dark');
console.log(isDark); // true

useBreakpoint

import { useBreakpoint } from '@webui/core';

const breakpoint = useBreakpoint();

if (breakpoint === 'sm') {
  // Mobile layout
} else if (breakpoint === 'lg') {
  // Desktop layout
}

💡 Tip: Hooks automatically clean up event listeners and resize observers on unmount. No manual cleanup required.

Accessibility

Webui is built with accessibility as a first-class concern. All components follow WAI-ARIA best practices and include proper keyboard navigation, focus management, and screen reader support.

Focus Management

Use the useFocusTrap hook for modals and dialogs to prevent focus from escaping:

import { useFocusTrap } from '@webui/core';

const { element } = useFocusTrap({
  initialFocus: '.confirm-btn',
  returnFocus: true
});

Reduced Motion

Webui automatically respects the operating system's prefers-reduced-motion setting. You can override this globally:

Webui.configure({
  accessibility: { reducedMotion: true }
});