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