# ngx-com An Angular component library built with signals, Tailwind CSS v4, and semantic design tokens. Requires Angular 21+. ## Installation ```bash npm install ngx-com ``` ### Peer dependencies **Required:** | Package | Version | | --- | --- | | `@angular/common` | `^21.0.0` | | `@angular/core` | `^21.0.0` | | `@angular/cdk` | `^21.0.0` | | `@angular/forms` | `^21.0.0` | | `rxjs` | `^7.8.0` | ```bash npm install @angular/cdk @angular/forms rxjs ``` > `@angular/common` and `@angular/core` are already present in every Angular project. **Optional:** | Package | Version | When needed | | --- | --- | --- | | `@angular/router` | `^21.0.0` | Only if using routed tab navigation (`comTabNavBar`) | | `lucide-angular` | `>=0.575.0 <1.0.0` | Only if using the Lucide icon adapter | ```bash # Install optional peer dependencies as needed npm install @angular/router # for routed tabs npm install lucide-angular # for Lucide icon adapter ``` ## Setup ### 1. Import the theme styles Add the library theme CSS to your application's stylesheet. This provides design tokens (colors, shadows, durations) and theme variants. ```css /* styles.css */ @import 'ngx-com/styles/themes.css'; ``` Or import individual files for finer control: | File | Contents | | ------------------ | --------------------------------------------- | | `tokens.css` | Base semantic tokens (light theme) | | `dark.css` | Dark theme override (`[data-theme='dark']`) | | `forest.css` | Forest theme (`[data-theme='forest']`) | | `ocean.css` | Ocean theme (`[data-theme='ocean']`) | | `candy.css` | Candy theme (`[data-theme='candy']`) | | `animations.css` | Keyframe animations used by components | | `utilities.css` | Utility classes | Switch themes at runtime by setting `data-theme` on the `` element. The library provides a theme service that handles this automatically: ```typescript import { provideComTheme } from 'ngx-com/theme'; export const appConfig: ApplicationConfig = { providers: [provideComTheme()], }; ``` See the [Theme service](#theme-service) section for details. ### 2. Add Tailwind source for ngx-com Library components use Tailwind utility classes in their templates. Tell Tailwind to scan the installed package so those classes are generated: ```css /* styles.css */ @source "../../node_modules/ngx-com"; ``` > The path is relative to your CSS file. Adjust the depth if your stylesheet > is not at `src/styles.css`. For **pnpm** with strict hoisting, the path may > be `../../node_modules/.pnpm/ngx-com@*/node_modules/ngx-com`. ### 3. Import CDK overlay styles Components that use overlays (dropdown, dialog, popover, tooltip, confirm, menu, toast) require the CDK overlay stylesheet: ```css @import '@angular/cdk/overlay-prebuilt.css'; ``` ### 4. Register icons (optional) If using the `` component with Lucide icons: ```typescript import { provideComLucideIcons } from 'ngx-com/components/icon/lucide'; import { Check, ChevronDown, X } from 'lucide-angular/icons/'; export const appConfig: ApplicationConfig = { providers: [ provideComLucideIcons({ Check, ChevronDown, X }), ], }; ``` Icons can also be registered at the route or component level. For custom (non-Lucide) SVG icons, use `provideComIcons` from `ngx-com/components/icon`. ## Usage Every component is a standalone import from its own entry point: ```typescript import { ComButton } from 'ngx-com/components/button'; import { ComDropdown, ComDropdownOption } from 'ngx-com/components/dropdown'; ``` ```html

``` ## Components | Component | Import path | Description | | ------------------ | ---------------------------------------- | ------------------------------------ | | Alert | `ngx-com/components/alert` | Contextual feedback messages | | Avatar | `ngx-com/components/avatar` | User or entity avatar | | Badge | `ngx-com/components/badge` | Small status indicator | | Button | `ngx-com/components/button` | Standard button directive | | Calendar | `ngx-com/components/calendar` | Date calendar grid | | Card | `ngx-com/components/card` | Content container with sections | | Carousel | `ngx-com/components/carousel` | Slideshow component | | Checkbox | `ngx-com/components/checkbox` | Checkbox input control | | Code Block | `ngx-com/components/code-block` | Syntax-highlighted code display | | Collapsible | `ngx-com/components/collapsible` | Expandable content section | | Confirm | `ngx-com/components/confirm` | Confirmation popover | | Datepicker | `ngx-com/components/datepicker` | Date input with calendar popup | | Dialog | `ngx-com/components/dialog` | Modal dialog service | | Dropdown | `ngx-com/components/dropdown` | Select / multi-select control | | Empty State | `ngx-com/components/empty-state` | Placeholder for empty content | | Form Field | `ngx-com/components/form-field` | Input wrapper with label and errors | | Icon | `ngx-com/components/icon` | SVG icon renderer | | Item | `ngx-com/components/item` | List item layout | | Menu | `ngx-com/components/menu` | Dropdown menu with keyboard nav | | Native Control | `ngx-com/components/native-control` | Styled native input/textarea | | Paginator | `ngx-com/components/paginator` | Pagination control | | Popover | `ngx-com/components/popover` | Floating content panel | | Radio | `ngx-com/components/radio` | Radio button group | | Segmented Control | `ngx-com/components/segmented-control` | Toggle between options | | Separator | `ngx-com/components/separator` | Horizontal/vertical divider | | Sort | `ngx-com/components/sort` | Column sort header for tables | | Spinner | `ngx-com/components/spinner` | Loading indicator | | Switch | `ngx-com/components/switch` | Toggle switch control | | Table | `ngx-com/components/table` | Data table with sorting and class customization | | Tabs | `ngx-com/components/tabs` | Tabbed navigation | | Timepicker | `ngx-com/components/timepicker` | Time input control | | Toast | `ngx-com/components/toast` | Toast notification service | | Tooltip | `ngx-com/components/tooltip` | Hover/focus tooltip | ## Services ### Theme service Import path: `ngx-com/theme` SSR-safe theme management with localStorage persistence and system `prefers-color-scheme` detection. Applies the active theme via a `data-theme` attribute on the document element. ```typescript import { provideComTheme, ComTheme } from 'ngx-com/theme'; // 1. Configure in app providers (zero-config works out of the box) providers: [provideComTheme()] // 2. Inject and use readonly theme = inject(ComTheme); this.theme.setTheme('dark'); // explicit override, persisted to localStorage this.theme.clearPreference(); // revert to following system preference this.theme.theme(); // current theme (Signal) this.theme.isAutomatic(); // true when following system preference ``` Configuration options: | Option | Type | Default | Description | | --- | --- | --- | --- | | `defaultTheme` | `string` | `'light'` | Fallback when no stored/system preference | | `storageKey` | `string \| null` | `'com-theme'` | localStorage key (`null` to disable) | | `darkSchemeTheme` | `string \| null` | `'dark'` | Theme for `prefers-color-scheme: dark` (`null` to disable) | | `lightSchemeTheme` | `string` | `defaultTheme` | Theme for light system preference | | `followSystemPreference` | `boolean` | `true` | Watch for live system preference changes | | `attribute` | `string` | `'data-theme'` | HTML attribute applied to `documentElement` | ## Utilities General-purpose utilities are available from `ngx-com/utils`. ## Requirements - Angular `^21.0.0` (`@angular/common`, `@angular/core`, `@angular/forms`) - `@angular/cdk` `^21.0.0` - RxJS `^7.8.0` - Tailwind CSS v4 (in the consuming application) - `@angular/router` `^21.0.0` (optional — for routed tab navigation) - `lucide-angular` `>=0.575.0 <1.0.0` (optional — for Lucide icon adapter) ## License MIT