Skip to content

craftedcode-dev/ngx-analog-clock

Repository files navigation

ngx-analog-clock

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

npm version License: MIT

🎨 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

About

Customizable analog clocks for Angular • Free, lightweight & easy to use

Resources

License

Stars

Watchers

Forks

Packages

No packages published