README.md

June 30, 2026 · View on GitHub

NGWR is a modern Angular UI library — standalone components, signals-first, zoneless-ready, responsive, modular SCSS, fully tree-shakable. Built on top of @angular/cdk for overlay, portal, and a11y primitives.

Status: active development. v8 is the current major line (Angular 22 peer). Public API is stable across patch releases and still evolving between majors. Open an issue if something breaks or feels wrong.

Requirements

Peer	Range
`@angular/core`	`>= 22.0.0`
`@angular/common`	`>= 22.0.0`
`@angular/cdk`	`>= 22.0.0`
`@angular/platform-browser`	`>= 22.0.0`
`rxjs`	`^7.0.0`
`date-fns` (optional)	`^3.0.0 \|\| ^4.0.0`
`luxon` (optional)	`^3.0.0`

Node ≥ 24.16.0 (or 26+). pnpm ≥ 11.8. TypeScript ≥ 6.0.

Install

pnpm add ngwr @angular/cdk
# or
npm install ngwr @angular/cdk
# or
yarn add ngwr @angular/cdk

Styles

The fastest way — pull in everything (theme tokens + all component styles):

// styles.scss
@use 'ngwr';

Prefer to opt in per-component? Each component has its own SCSS entry that pulls in the theme automatically:

@use 'ngwr/theme'; // CSS custom properties (--wr-color-*, --wr-font-*, etc.)
@use 'ngwr/button';
@use 'ngwr/input';
@use 'ngwr/checkbox';

Opt-in utilities (not part of @use 'ngwr'):

@use 'ngwr/reset'; // box-sizing, body margin, sane defaults
@use 'ngwr/grid'; // .grid, .container, .col-*
@use 'ngwr/breakpoints' as bp; // SCSS mixins only, no CSS output

Quick start

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideWrOverlay } from 'ngwr/overlay';

import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    provideWrOverlay(), // isolated overlay container
  ],
});

// app.component.ts
import { Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { Check } from 'lucide';
import { WrButton } from 'ngwr/button';
import { provideWrIcons } from 'ngwr/icon';
import { lucideIcons } from 'ngwr/icon/adapters/lucide';
import { WrInput } from 'ngwr/input';

@Component({
  selector: 'app-root',
  imports: [FormsModule, WrButton, WrInput],
  providers: [provideWrIcons(lucideIcons({ checkmark: Check }))], // tree-shaken icons
  template: `
    <input wrInput [(ngModel)]="name" placeholder="Your name" />
    <button wr-btn color="primary" icon="checkmark" (click)="greet()">Hello</button>
  `,
})
export class AppComponent {
  readonly name = signal('');
  greet(): void {
    console.log('Hi', this.name());
  }
}

Catalog

Browse the full catalog with live demos at ngwr.dev. Each entry below is a tree-shakable subpath — import { … } from 'ngwr/<name>'.

Components

Form — calendar, cascader, checkbox, color-picker, date-picker, file-upload, form, form-field, input, input-number, input-otp, knob, mention, radio, rating, segmented, select, slider, switch, textarea.

Buttons — button, button-group, speed-dial.

Data — drag-drop, pagination, table, tree, virtual-scroll.

Feedback — alert, empty, progress, result, skeleton, spinner.

Display — avatar, badge (incl. wr-tag), compare, counter, descriptions, divider, image-cropper, keyboard, lightbox, qrcode, statistic, timeline.

Layout — card, carousel, collapse, layout, list, page-header, splitter, toolbar.

Navigation — anchor, back-top, breadcrumbs, burger, dropdown, sidebar, stepper, tabs.

Overlays — command-palette, context-menu, dialog, drawer, popconfirm, popover, toast, window.

Charts — bar-chart, calendar-heatmap, donut-chart, gauge, line-chart, meter-group, sparkline.

Plus icon, the experimental squircle, and the typography directive.

Animations

Animated UI effects. Mix of in-house components + ports of reactbits.dev — each port carries a credit chip on its docs page. Defaults are theme-aware (light + dark), and every component honors prefers-reduced-motion.

aurora, blur-text, border-glow, circular-text, click-spark, confetti, decrypt-text, falling-text, fuzzy-text, glitch-text, gradient-text, marquee, rotating-text, shiny-text, splash-cursor, split-text, spotlight-card, star-border, tilt-card, typewriter, waves.

Card packages bundle their related directives: ngwr/spotlight-card exports WrSpotlight; ngwr/tilt-card exports WrTilt; ngwr/shiny-text exports WrShimmer.

Validators — `ngwr/validators`

Bundled ValidatorFns composing cleanly with Angular's built-in Validators: cardNumber (Luhn), cvc, hexColor, iban (mod-97), match (sibling control), maxDate, minDate, noWhitespace, oneOf, url. See docs.

Utils — `ngwr/utils`

Math (clamp, round), coercion (numAttr), css helpers (resolveCssSize, getRootFontSize), ids (randomId), type guards (isDefined, isNonEmptyArray, isObservable), keyboard helpers (KEYS, hasModifier, isPrintableKey), functional primitives (noop, badgeLog, debounce, throttle), focus management (getFocusableElements, trapFocus). See docs for the full list. Shared shapes (Maybe, SafeAny, WrColor, …) are documented under Interfaces.

Core

Color — design tokens and palette.
Grid — opt-in 12-column layout.
Overlay — isolated CDK overlay container, provideWrOverlay().
Mobile & responsive — responsive overlays, touch targets & density, swipe gestures, safe-area insets, container-query layouts.
Typography — wrTypography directive: headings, paragraphs, lists, links, code.
Icons — ngwr/icon registry + thin adapters for Lucide, Feather, Tabler, Phosphor, Heroicons, Iconoir, Radix, Bootstrap.
Date adapters — ngwr/date-adapter-fns, ngwr/date-adapter-luxon. Wire one with provideWrDateAdapter(...) to power calendar + every mode of date-picker.

Highlights

Standalone & signals-first. Every component is standalone and uses input() / model() / output() / signal() / computed(). Zoneless-ready.
CDK-powered. Overlays, portals, and a11y come from @angular/cdk. We add provideWrOverlay() so NGWR overlays never collide with other CDK consumers (Material, NG-ZORRO, etc.).
Mobile & responsive. Overlays collapse to bottom-sheets on small screens (provideWrResponsiveOverlays()), touch targets grow to ≥44px on coarse pointers, a touch density preset enlarges every control, and drawer / lightbox / toast / carousel respond to swipe gestures. Fixed surfaces respect env(safe-area-inset-*), and layout components (descriptions, stepper, page-header, toolbar, pagination, table, tabs) reflow to their container via container queries. Guide.
Tree-shakable. 127 separate ng-packagr entry points — import only what you use. Per-component FESM bundles are small: a median of ~3 KB gzipped, the heaviest (ngwr/window) ~15 KB. The whole catalog gzips to ~320 KB — but real apps pull a handful of entries. The only runtime dependency is tslib.
Modular SCSS. Component styles are scoped through CSS custom properties. Theme tokens live in ngwr/theme; utilities (grid, reset) and the breakpoints SCSS API are opt-in.
Tree-shaken icons. provideWrIcons([plus, trash]) registers only the icons you actually import. Dev-mode validation warns about unregistered icons.
Reactbits ports, dependency-free. All animation ports are reimplemented with vanilla DOM + Web Animations API / IntersectionObserver / requestAnimationFrame / raw WebGL — no GSAP, no motion/react, no matter-js, no ogl.
Motion respects the OS. Every animation component short-circuits to its final state under prefers-reduced-motion.

Contributing

Conventional commits are enforced on PR titles. Common types: feat, fix, perf, refactor, docs, style, test, build, ci, chore, revert. Optional scope is the component or area (feat(checkbox): icon mode).

pnpm install
pnpm dev            # ng serve --o (showcase)
pnpm build:lib      # ng build lib
pnpm build:showcase # ng build showcase
pnpm lint           # ng lint

Authors

Roman Khegay — code, design

License

MIT — free for commercial use.