ngxsmk-datepicker
Version:
<!-- SEO Keywords: Angular DatePicker, Angular Date Range Picker, Lightweight Calendar Component, Angular Signals DatePicker, SSR Ready DatePicker, Zoneless Angular, A11y DatePicker, Mobile-Friendly DatePicker, Ionic DatePicker Meta Description: The
324 lines (253 loc) • 11 kB
Markdown
# Theme Tokens & CSS Custom Properties
**Last updated:** May 2, 2026 · **Current stable:** v2.2.12
Complete reference for all CSS custom properties (CSS variables) available in ngxsmk-datepicker.
## Overview
ngxsmk-datepicker uses CSS custom properties for theming, allowing you to customize the appearance without modifying the component's internal styles. All variables are prefixed with `--datepicker-` and can be overridden at any level in your CSS.
## Color Tokens
### Primary Colors
| Variable | Default (Light) | Default (Dark) | Description |
|----------|----------------|----------------|-------------|
| `--datepicker-primary-color` | `#6d28d9` | `#8b5cf6` | Primary brand color for selected dates, buttons, and focus states |
| `--datepicker-primary-contrast` | `#ffffff` | `#ffffff` | Text color on primary color background |
### Background Colors
| Variable | Default (Light) | Default (Dark) | Description |
|----------|----------------|----------------|-------------|
| `--datepicker-background` | `#ffffff` | `#1f2937` | Main background color for calendar container |
| `--datepicker-range-background` | `#f5f3ff` | `rgba(139, 92, 246, 0.15)` | Background color for date range selection |
| `--datepicker-hover-background` | `#f3f4f6` | `#374151` | Background color for hover states |
### Text Colors
| Variable | Default (Light) | Default (Dark) | Description |
|----------|----------------|----------------|-------------|
| `--datepicker-text-color` | `#1f2937` | `#f3f4f6` | Primary text color |
| `--datepicker-subtle-text-color` | `#6b7280` | `#9ca3af` | Secondary/subtle text color for labels and hints |
### Border Colors
| Variable | Default (Light) | Default (Dark) | Description |
|----------|----------------|----------------|-------------|
| `--datepicker-border-color` | `#e5e7eb` | `#374151` | Border color for inputs, calendar, and dividers |
## Shadow Tokens
| Variable | Default (Light) | Default (Dark) | Description |
|----------|----------------|----------------|-------------|
| `--datepicker-shadow-sm` | `0 1px 2px 0 rgba(0, 0, 0, 0.05)` | `0 1px 2px 0 rgba(0, 0, 0, 0.3)` | Small shadow for subtle elevation |
| `--datepicker-shadow-md` | `0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)` | `0 4px 6px -1px rgba(0, 0, 0, 0.3), 0 2px 4px -1px rgba(0, 0, 0, 0.2)` | Medium shadow for popover and elevated elements |
| `--datepicker-shadow-lg` | `0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)` | `0 10px 15px -3px rgba(0, 0, 0, 0.3), 0 4px 6px -2px rgba(0, 0, 0, 0.2)` | Large shadow for modal overlays |
| `--datepicker-shadow-xl` | `0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)` | Same as light | Extra large shadow (not used in dark theme) |
## Typography Tokens
| Variable | Default | Description |
|----------|---------|-------------|
| `--datepicker-font-size-base` | `14px` | Base font size for most text |
| `--datepicker-font-size-sm` | `12px` | Small font size for labels and hints |
| `--datepicker-font-size-lg` | `16px` | Large font size for headers |
| `--datepicker-font-size-xl` | `18px` | Extra large font size |
| `--datepicker-line-height` | `1.5` | Line height for text |
## Spacing Tokens
| Variable | Default | Description |
|----------|---------|-------------|
| `--datepicker-spacing-xs` | `4px` | Extra small spacing |
| `--datepicker-spacing-sm` | `8px` | Small spacing |
| `--datepicker-spacing-md` | `12px` | Medium spacing (default) |
| `--datepicker-spacing-lg` | `16px` | Large spacing |
| `--datepicker-spacing-xl` | `20px` | Extra large spacing |
| `--datepicker-spacing-2xl` | `24px` | 2X large spacing |
## Border Radius Tokens
| Variable | Default | Description |
|----------|---------|-------------|
| `--datepicker-radius-sm` | `6px` | Small border radius |
| `--datepicker-radius-md` | `8px` | Medium border radius (default) |
| `--datepicker-radius-lg` | `12px` | Large border radius |
| `--datepicker-radius-xl` | `16px` | Extra large border radius |
## Transition Tokens
| Variable | Default | Description |
|----------|---------|-------------|
| `--datepicker-transition` | `opacity 0.15s cubic-bezier(0.4, 0, 0.2, 1), transform 0.15s cubic-bezier(0.4, 0, 0.2, 1), background-color 0.15s cubic-bezier(0.4, 0, 0.2, 1), border-color 0.15s cubic-bezier(0.4, 0, 0.2, 1), box-shadow 0.15s cubic-bezier(0.4, 0, 0.2, 1)` | Default transition for animations |
## Global CSS Variables Override
When CSS variables are defined in a global `:root` selector, the ThemeBuilderService will now properly override them with enhanced specificity and `!important` flags to ensure your theme values take precedence.
```css
/* When CSS variables are defined in global :root selector */
:root {
--datepicker-primary-color: #ff0000;
--datepicker-primary-contrast: #ffffff;
}
/* ThemeBuilderService will now properly override these global variables */
```
**Note**: If you have CSS variables defined in a global `:root` selector, ThemeBuilderService will now properly override them with enhanced specificity and `!important` flags to ensure your theme values take precedence.
## Usage Examples
### Basic Theme Override
```css
/* Override at component level */
ngxsmk-datepicker {
--datepicker-primary-color: #3b82f6;
--datepicker-primary-contrast: #ffffff;
--datepicker-range-background: #dbeafe;
}
```
### Brand Color Theme
```css
/* Blue brand theme */
ngxsmk-datepicker {
--datepicker-primary-color: #2563eb;
--datepicker-primary-contrast: #ffffff;
--datepicker-range-background: #dbeafe;
--datepicker-border-color: #93c5fd;
--datepicker-hover-background: #eff6ff;
}
```
### Green Brand Theme
```css
/* Green brand theme */
ngxsmk-datepicker {
--datepicker-primary-color: #10b981;
--datepicker-primary-contrast: #ffffff;
--datepicker-range-background: #d1fae5;
--datepicker-border-color: #6ee7b7;
--datepicker-hover-background: #ecfdf5;
}
```
### Compact Mode
```css
/* Compact spacing for dense UIs */
ngxsmk-datepicker {
--datepicker-spacing-xs: 2px;
--datepicker-spacing-sm: 4px;
--datepicker-spacing-md: 6px;
--datepicker-spacing-lg: 8px;
--datepicker-spacing-xl: 12px;
--datepicker-spacing-2xl: 16px;
--datepicker-font-size-base: 12px;
--datepicker-font-size-sm: 10px;
--datepicker-radius-md: 4px;
--datepicker-radius-sm: 2px;
}
```
### High Contrast Theme
```css
/* High contrast for accessibility */
ngxsmk-datepicker {
--datepicker-primary-color: #000000;
--datepicker-primary-contrast: #ffffff;
--datepicker-background: #ffffff;
--datepicker-text-color: #000000;
--datepicker-border-color: #000000;
--datepicker-hover-background: #f0f0f0;
--datepicker-range-background: #e0e0e0;
}
```
### Material Design Theme
```css
/* Material Design inspired */
ngxsmk-datepicker {
--datepicker-primary-color: #6200ee;
--datepicker-primary-contrast: #ffffff;
--datepicker-range-background: #e1bee7;
--datepicker-border-color: #b39ddb;
--datepicker-hover-background: #f3e5f5;
--datepicker-radius-md: 4px;
--datepicker-shadow-md: 0 2px 4px rgba(0,0,0,0.2);
}
```
### Tailwind Integration
```css
/* Using Tailwind CSS variables */
ngxsmk-datepicker {
--datepicker-primary-color: var(--tw-color-blue-600);
--datepicker-primary-contrast: var(--tw-color-white);
--datepicker-background: var(--tw-color-white);
--datepicker-text-color: var(--tw-color-gray-900);
--datepicker-border-color: var(--tw-color-gray-300);
--datepicker-hover-background: var(--tw-color-gray-100);
}
```
### Design System Integration (TokiForge)
```css
/* TokiForge design tokens */
ngxsmk-datepicker {
--datepicker-primary-color: var(--toki-color-primary);
--datepicker-primary-contrast: var(--toki-color-on-primary);
--datepicker-background: var(--toki-color-surface);
--datepicker-text-color: var(--toki-color-on-surface);
--datepicker-border-color: var(--toki-color-outline);
--datepicker-hover-background: var(--toki-color-surface-variant);
--datepicker-spacing-md: var(--toki-spacing-md);
--datepicker-radius-md: var(--toki-radius-md);
}
```
## Scoped Theming
You can apply different themes to different datepicker instances:
```css
/* Theme for specific datepicker */
.my-custom-datepicker {
--datepicker-primary-color: #ec4899;
--datepicker-range-background: #fce7f3;
}
/* Another theme for different datepicker */
.my-other-datepicker {
--datepicker-primary-color: #06b6d4;
--datepicker-range-background: #cffafe;
}
```
```html
<ngxsmk-datepicker class="my-custom-datepicker" mode="single"></ngxsmk-datepicker>
<ngxsmk-datepicker class="my-other-datepicker" mode="range"></ngxsmk-datepicker>
```
## Dark Theme
The component automatically applies dark theme variables when `[theme]="'dark'"` is set:
```html
<ngxsmk-datepicker [theme]="'dark'"></ngxsmk-datepicker>
```
You can also override dark theme variables:
```css
ngxsmk-datepicker.dark-theme {
--datepicker-primary-color: #a78bfa;
--datepicker-background: #111827;
}
```
## Complete Variable List
For reference, here's the complete list of all CSS custom properties:
```css
/* Colors */
--datepicker-primary-color
--datepicker-primary-contrast
--datepicker-range-background
--datepicker-background
--datepicker-text-color
--datepicker-subtle-text-color
--datepicker-border-color
--datepicker-hover-background
/* Shadows */
--datepicker-shadow-sm
--datepicker-shadow-md
--datepicker-shadow-lg
--datepicker-shadow-xl
/* Typography */
--datepicker-font-size-base
--datepicker-font-size-sm
--datepicker-font-size-lg
--datepicker-font-size-xl
--datepicker-line-height
/* Spacing */
--datepicker-spacing-xs
--datepicker-spacing-sm
--datepicker-spacing-md
--datepicker-spacing-lg
--datepicker-spacing-xl
--datepicker-spacing-2xl
/* Border Radius */
--datepicker-radius-sm
--datepicker-radius-md
--datepicker-radius-lg
--datepicker-radius-xl
/* Transitions */
--datepicker-transition
```
## Best Practices
1. **Use CSS Variables**: Always use CSS custom properties for theming, not direct style overrides
2. **Scope Appropriately**: Apply theme variables at the appropriate scope (component, page, or global)
3. **Maintain Contrast**: Ensure sufficient contrast ratios for accessibility (WCAG AA minimum)
4. **Test Dark Mode**: Always test your custom themes in both light and dark modes
5. **Use Design Tokens**: Integrate with your design system's token system when available
## Browser Support
CSS custom properties are supported in all modern browsers:
- Chrome 49+
- Firefox 31+
- Safari 9.1+
- Edge 15+
For older browsers, consider using a CSS custom properties polyfill or provide fallback values.