ngx-analog-clock

A beautiful, customizable analog clock component for Angular applications with timezone support, custom themes, and extensive styling options.

🎨 Demo

Live Demo & Interactive Playground

Explore pre-built designs and create your own custom clock with our interactive playground.

✨ Features

• 🎨 Multiple Themes - Light, Dark, and fully Custom themes
• 🌍 Timezone Support - Display time from any timezone using IANA strings
• ⏱️ Custom Time Control - Perfect for timers and countdowns
• 🎨 Full Customization - Colors, gradients, sizes, and styles
• 📱 Responsive - Works seamlessly on all screen sizes
• ⚡ Smooth Animations - 30 FPS second hand movement
• 🎯 TypeScript - Full type definitions included
• 📦 Lightweight - Optimized performance with minimal bundle size

📦 Installation

npm install @craftedcode-dev/ngx-analog-clock

🚀 Quick Start

1. Import the component:

import { Component } from '@angular/core';
import { AnalogClockComponent } from '@craftedcode-dev/ngx-analog-clock';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [AnalogClockComponent],
  template: '<ngx-analog-clock></ngx-analog-clock>'
})
export class AppComponent {}

2. Basic customization:

import { AnalogClockConfig } from '@craftedcode-dev/ngx-analog-clock';

export class MyComponent {
  clockConfig: AnalogClockConfig = {
    size: 300,
    theme: 'dark'
  };
}

<ngx-analog-clock [config]="clockConfig"></ngx-analog-clock>

📚 API Reference

Basic Configuration

| Property | Type | Default | Description | |----------|------|---------|-------------| | size | number | 300 | Clock diameter in pixels | | theme | 'light' \| 'dark' \| 'custom' | 'light' | Pre-built theme or custom for full control | | timezone | string | 'local' | IANA timezone string (e.g., 'America/New_York') | | time | Date | undefined | Custom time to display (for timers/countdowns) |

Hands Configuration

Configure via config.hands:

| Property | Type | Default | Description | |----------|------|---------|-------------| | hour.length | number | 0.55 | Length as fraction of radius (0.1-0.9) | | hour.width | number | 6 | Width in pixels | | hour.show | boolean | true | Show/hide hour hand | | minute.length | number | 0.7 | Length as fraction of radius (0.1-0.9) | | minute.width | number | 6 | Width in pixels | | minute.show | boolean | true | Show/hide minute hand | | second.length | number | 0.8 | Length as fraction of radius (0.1-0.9) | | second.width | number | 4 | Width in pixels | | second.show | boolean | true | Show/hide second hand | | smooth | boolean | true | Enable smooth animation |

Display Configuration

Configure via config.display:

| Property | Type | Default | Description | |----------|------|---------|-------------| | markers | 'lines' \| 'numbers' \| 'dots' \| 'lines-numbers' \| 'dots-numbers' \| 'none' | 'lines' | Hour markers: lines (traditional), dots (circular), numbers (1-12), lines-numbers (lines + cardinal numbers), dots-numbers (dots + cardinal numbers), or none | | numberStyle | 'arabic' \| 'roman' | 'arabic' | Number style: Arabic (1-12) or Roman numerals (I-XII) | | showBorder | boolean | true | Show clock border | | showInnerRing | boolean | true | Show inner decorative ring | | showCenterRing | boolean | true | Show ring around center | | hourMarkerWidth | number | 3 | Size of hour markers in pixels. Works for both lines (stroke width) and dots (radius) | | minuteMarkerWidth | number | 1 | Size of minute markers in pixels. Works for both lines (stroke width) and dots (radius) | | borderWidth | number | 10 | Border width in pixels | | numberSize | number | 16 | Font size for numbers | | numberWeight | 'light' \| 'normal' \| 'bold' | 'bold' | Font weight for numbers |

Custom Colors

Configure via config.customColors (only applies when theme is 'custom'):

| Property | Type | Description | |----------|------|-------------| | hands.hour | string | Hour hand color | | hands.minute | string | Minute hand color | | hands.second | string | Second hand color | | markers.hour | string | Hour markers color (works for both line and dot markers) | | markers.minute | string | Minute markers color (works for both line and dot markers) | | markers.numbers | string | Numbers color | | center.dot | string | Center dot color | | center.ring | string | Center ring color | | background | string | Clock face background | | border | string | Clock border color | | innerRing | string | Inner ring color | | label | string | Label text color |

Gradient Backgrounds

Configure via config.customColors.backgroundGradient:

| Property | Type | Default | Description | |----------|------|---------|-------------| | type | 'linear' \| 'radial' | - | Gradient type | | start | string | - | Start color | | end | string | - | End color | | angle | number | 45 | Angle in degrees (linear only) |

Digital Display

Configure via config.digitalDisplay:

| Property | Type | Default | Description | |----------|------|---------|-------------| | enabled | boolean | false | Show digital time display | | format | '12h' \| '24h' | '24h' | Time format | | showSeconds | boolean | true | Show seconds in digital display | | showDate | boolean | false | Show date in digital display | | color | string | theme-dependent | Custom color for digital display text |

Label

Configure via config.label:

| Property | Type | Default | Description | |----------|------|---------|-------------| | text | string | - | Label text (e.g., timezone name) | | position | 'top' \| 'bottom' | 'bottom' | Label position |

💡 Usage Examples

Timezone Clock

clockConfig: AnalogClockConfig = {
  size: 250,
  timezone: 'America/New_York',
  label: {
    text: 'New York',
    position: 'bottom'
  },
  digitalDisplay: {
    enabled: true,
    format: '12h'
  }
};

Modern Dot Markers

clockConfig: AnalogClockConfig = {
  size: 250,
  theme: 'custom',
  display: {
    markers: 'dots-numbers',
    hourMarkerWidth: 5,
    numberWeight: 'bold'
  },
  customColors: {
    background: '#f0f9ff',
    border: '#0ea5e9',
    hands: {
      hour: '#0c4a6e',
      minute: '#0369a1',
      second: '#e11d48'
    },
    markers: {
      hour: '#075985',
      numbers: '#0c4a6e'
    }
  }
};

Custom Theme

clockConfig: AnalogClockConfig = {
  theme: 'custom',
  customColors: {
    hands: {
      hour: '#3b82f6',
      minute: '#60a5fa',
      second: '#93c5fd'
    },
    markers: {
      hour: '#1e40af',
      minute: '#3b82f6'
    },
    background: '#ffffff',
    border: '#e0e7ff'
  }
};

Gradient Background

clockConfig: AnalogClockConfig = {
  theme: 'custom',
  customColors: {
    backgroundGradient: {
      type: 'radial',
      start: '#667eea',
      end: '#764ba2'
    },
    hands: {
      hour: '#ffffff',
      minute: '#ffffff',
      second: '#fbbf24'
    }
  }
};

Timer/Countdown

export class TimerComponent implements OnInit {
  customTime: Date = new Date();
  
  clockConfig: AnalogClockConfig = {
    size: 300,
    theme: 'dark'
  };

  ngOnInit() {
    // Update every second
    setInterval(() => {
      this.customTime = new Date(this.customTime.getTime() + 1000);
    }, 1000);
  }
}

<ngx-analog-clock 
  [time]="customTime" 
  [config]="clockConfig">
</ngx-analog-clock>

📖 Documentation

For detailed documentation, interactive examples, and the playground, visit:

Full Documentation

🛠️ Requirements

• Angular 17+
• TypeScript 5.0+

📄 License

MIT © 2025 craftedcode-dev