@shival99/z-ui

v1.4.12

Published

3 hours ago

Z-UI: Modern Angular UI Component Library - A comprehensive, high-performance design system built with Angular 20+, featuring 40+ customizable components with dark mode, accessibility, and enterprise-ready features.

Downloads

14,399

Z-UI - Modern Angular Component Library

A comprehensive, high-performance UI component library built with Angular 21+, featuring 40+ customizable components with dark mode, accessibility, and enterprise-ready features.

Features

40+ Components - Buttons, Inputs, Tables, Modals, Calendars, and more
Dark Mode - Built-in theme support with 9 color themes
Accessible - WCAG 2.1 compliant components
Responsive - Mobile-first responsive design
High Performance - OnPush change detection, virtual scrolling
Customizable - CSS variables, class-variance-authority
Tree-shakable - Import only what you need
Type-safe - Full TypeScript support with strict mode
i18n Ready - Built-in translation support

Installation

pnpm add @shival99/z-ui

Peer Dependencies

pnpm add @angular/cdk @ng-icons/core @ng-icons/lucide @ng-icons/iconsax \
  @tanstack/angular-table @shival99/angular-virtual \
  class-variance-authority clsx tailwind-merge \
  ngx-mask ngx-scrollbar @shival99/ngx-sonner ngxtension minisearch

Optional Dependencies

pnpm add ngx-quill quill                    # Rich Text Editor
pnpm add shiki dompurify                    # Syntax Highlighting
pnpm add echarts ngx-echarts                # Charts
pnpm add @ngx-translate/core @ngx-translate/http-loader  # i18n
pnpm add exceljs file-saver xlsx            # Excel Export

Tailwind CSS v4 Setup

Z-UI requires Tailwind CSS v4. Install the dependencies:

pnpm add -D tailwindcss @tailwindcss/postcss postcss

Create postcss.config.mjs in your project root:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Update your project.json or angular.json styles:

"styles": [
  "node_modules/@shival99/z-ui/assets/css/themes/green.css",
  "node_modules/@shival99/z-ui/assets/css/tailwind.css",
  "src/styles.scss"
]

Copy theme files to assets for lazy loading (optional):

"assets": [
  {
    "glob": "*.css",
    "input": "node_modules/@shival99/z-ui/assets/css/themes",
    "output": "assets/css/themes"
  }
]

Quick Start

Import Components

import { ZButtonComponent } from '@shival99/z-ui/components/z-button';
import { ZInputComponent } from '@shival99/z-ui/components/z-input';
import { ZTableComponent } from '@shival99/z-ui/components/z-table';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ZButtonComponent, ZInputComponent, ZTableComponent],
  template: `
    <z-button zVariant="primary">Click me</z-button>
    <z-input zLabel="Email" zPlaceholder="Enter email" />
  `,
})
export class AppComponent {}

Configure Providers

import { provideZTranslate } from '@shival99/z-ui/providers';
import { provideZNgxMask } from '@shival99/z-ui/providers';

export const appConfig: ApplicationConfig = {
  providers: [provideZTranslate({ defaultLang: 'vi', langPath: '/assets/i18n/' }), provideZNgxMask()],
};

Components

| Category | Components | | ----------- | ---------------------------------------------------------------- | | Form | Input, Select, Checkbox, Radio, Switch, Calendar, Upload, Filter | | Data | Table, Pagination, Code, Editor, Timeline | | Overlay | Modal, Drawer, Toast, Tooltip, Popover, Dropdown Menu | | Layout | Accordion, Tabs, Menu, Breadcrumb, Skeleton | | Display | Button, Icon, Loading |

Import Paths

import { ZButtonComponent } from '@shival99/z-ui/components/z-button';
import { ZTableComponent } from '@shival99/z-ui/components/z-table';
import { ZModalService } from '@shival99/z-ui/components/z-modal';

import { ZThemeService, ZCacheService } from '@shival99/z-ui/services';
import { provideZTranslate } from '@shival99/z-ui/providers';
import { zTransform, zMergeClasses } from '@shival99/z-ui/utils';
import { ZSafeHtmlPipe } from '@shival99/z-ui/pipes';
import { Z_UI_TRANSLATIONS } from '@shival99/z-ui/i18n';

Theming

Available themes: green, orange, violet, neutral, zinc, slate, stone, gray, hospital

import { ZThemeService } from '@shival99/z-ui/services';

export class AppComponent {
  private themeService = inject(ZThemeService);

  ngOnInit() {
    this.themeService.setTheme('violet');
    this.themeService.toggleDarkMode(true);
  }
}

CSS Variables

Z-UI uses CSS variables for customization. You can override these variables in your project's CSS to customize the look and feel.

Font Variables

Override these in your styles.css or styles.scss:

:root {
  --font-sans: 'Be Vietnam Pro', system-ui, -apple-system, sans-serif;
  --font-mono: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, 'Courier New', monospace;
}

Example - Using Inter font:

:root {
  --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
}

Theme Variables (Light Mode)

:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0.031 264.539);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0.031 264.539);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0.031 264.539);
  --primary: oklch(0.422 0.095 166.913);
  --primary-foreground: oklch(0.982 0.018 166.913);
  --secondary: oklch(0.967 0.004 264.539);
  --secondary-foreground: oklch(0.209 0.021 264.539);
  --muted: oklch(0.967 0.004 264.539);
  --muted-foreground: oklch(0.556 0.024 264.539);
  --accent: oklch(0.967 0.004 264.539);
  --accent-foreground: oklch(0.209 0.021 264.539);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.985 0 0);
  --border: oklch(0.929 0.007 264.539);
  --input: oklch(0.929 0.007 264.539);
  --input-autofill: oklch(1 0 0);
  --ring: oklch(0.422 0.095 166.913);
  --chart-1: oklch(0.646 0.222 41.116);
  --chart-2: oklch(0.6 0.118 184.704);
  --chart-3: oklch(0.398 0.07 227.334);
  --chart-4: oklch(0.828 0.189 84.429);
  --chart-5: oklch(0.769 0.188 70.08);
  --sidebar: oklch(0.985 0.001 264.539);
  --sidebar-foreground: oklch(0.145 0.031 264.539);
  --sidebar-primary: oklch(0.422 0.095 166.913);
  --sidebar-primary-foreground: oklch(0.982 0.018 166.913);
  --sidebar-accent: oklch(0.967 0.004 264.539);
  --sidebar-accent-foreground: oklch(0.209 0.021 264.539);
  --sidebar-border: oklch(0.929 0.007 264.539);
  --sidebar-ring: oklch(0.422 0.095 166.913);
}

Theme Variables (Dark Mode)

.dark {
  --background: oklch(0.145 0.031 264.539);
  --foreground: oklch(0.985 0.001 264.539);
  --card: oklch(0.209 0.021 264.539);
  --card-foreground: oklch(0.985 0.001 264.539);
  --popover: oklch(0.209 0.021 264.539);
  --popover-foreground: oklch(0.985 0.001 264.539);
  --primary: oklch(0.696 0.17 162.48);
  --primary-foreground: oklch(0.209 0.021 264.539);
  --secondary: oklch(0.268 0.019 264.539);
  --secondary-foreground: oklch(0.985 0.001 264.539);
  --muted: oklch(0.268 0.019 264.539);
  --muted-foreground: oklch(0.708 0.019 264.539);
  --accent: oklch(0.268 0.019 264.539);
  --accent-foreground: oklch(0.985 0.001 264.539);
  --destructive: oklch(0.704 0.191 22.216);
  --destructive-foreground: oklch(0.985 0 0);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --input-autofill: oklch(0.19 0 0);
  --ring: oklch(0.527 0.154 150.069);
  --chart-1: oklch(0.488 0.243 264.376);
  --chart-2: oklch(0.696 0.17 162.48);
  --chart-3: oklch(0.769 0.188 70.08);
  --chart-4: oklch(0.627 0.265 303.9);
  --chart-5: oklch(0.645 0.246 16.439);
  --sidebar: oklch(0.209 0.021 264.539);
  --sidebar-foreground: oklch(0.985 0.001 264.539);
  --sidebar-primary: oklch(0.696 0.17 162.48);
  --sidebar-primary-foreground: oklch(0.209 0.021 264.539);
  --sidebar-accent: oklch(0.268 0.019 264.539);
  --sidebar-accent-foreground: oklch(0.985 0.001 264.539);
  --sidebar-border: oklch(1 0 0 / 10%);
  --sidebar-ring: oklch(0.527 0.154 150.069);
}

Scrollbar Variables

:root {
  --scrollbar-track-color: transparent;
  --scrollbar-track-shape: 5px;
  --scrollbar-track-thickness: 7px;
  --scrollbar-thumb-color: #d1d5db;
  --scrollbar-thumb-hover-color: #9ca3af;
  --scrollbar-thumb-shape: 5px;
  --scrollbar-thumb-min-size: 40;
  --scrollbar-hover-opacity-transition-leave-duration: 0.3s;
  --scrollbar-hover-opacity-transition-leave-delay: 0.5s;
}

.dark {
  --scrollbar-thumb-color: #4b5563;
  --scrollbar-thumb-hover-color: #6b7280;
}

Example: Custom Override

Create a custom theme by overriding variables in your project:

/* styles.css */
:root {
  /* Custom font */
  --font-sans: 'Roboto', system-ui, sans-serif;

  /* Custom primary color */
  --primary: oklch(0.6 0.2 240);
  --primary-foreground: oklch(1 0 0);

  /* Custom border radius */
  --radius: 0.5rem;
}

.dark {
  /* Dark mode primary color */
  --primary: oklch(0.7 0.2 240);
}