react-time-ticker

A customizable countdown timer component for React applications. The react-time-ticker component displays a countdown timer with various units and styling options.

Table of Contents

• Features
• Prerequisites
• Installation
• Usage
  • Basic Example
  • Advanced Example with Custom Styling
  • Props
  • Styles
  • Units
  • Labels
• Demo
• Changelog
• Contributing
• License

Features

• Display time in years, months, days, hours, minutes, and seconds.
• Customizable labels and styles.
• Responsive design with support for single and double-line layouts.
• Countdown functionality with a callback for when the countdown ends.
• Configurable display units (e.g., show only hours and minutes, hide seconds).

Prerequisites

Before using this component, ensure that you have the following:

• React: v16.8 or higher.
• Node.js: v12 or higher.
• A package manager like npm or yarn.

Installation

To install the TimeTicker component, use npm or yarn:

npm install react-time-ticker

or

yarn add react-time-ticker

Usage

Basic Example

The most basic usage of the react-time-ticker component involves providing an initialSeconds prop for the countdown and an optional onTimesUp callback.

import React from 'react';
import TimeTicker from 'react-time-ticker';

const App = () => (
<TimeTicker
initialSeconds={3600} // 1 hour countdown
onTimesUp={() => console.log('Time is up!')}
/>
);

export default App;

Advanced Example with Custom Styling

In this example, we will customize the appearance of the TimeTicker by passing customStyles, and only show hours, minutes, and seconds.

import React from 'react';
import TimeTicker from 'react-time-ticker';

const App = () => (
  <TimeTicker
    initialSeconds={7200} // 2 hours countdown
    displayUnitsConfig={{
      hours: true,
      minutes: true,
      seconds: true,
    }}
    customStyles={{
      digitBg: '#222222',
      digitColor: '#FFFFFF',
      digitFontSize: '1.5rem',
      labelColor: '#F1C40F',
      labelFontSize: '0.875rem',
      labelBg: '#333333',
      separatorColor: '#E74C3C',
    }}
    labels={{
      hours: 'Hours',
      minutes: 'Minutes',
      seconds: 'Seconds',
    }}
    emphasizeLabels={false}
    isDoubleLine={true}
    onTimesUp={() => alert('Countdown finished!')}
  />
);

export default App;

Props

| Name | Type | Default Value | Description | |----------------------|--------------|---------------|---------------------------------------------------------------------------------| | initialSeconds | number | 0 | The initial time in seconds. | | displayUnitsConfig | object | * | Configures which time units are displayed (years, months, days, etc.). | | onTimesUp | () => void | () => {} | Callback function that is called when the timer ends. | | customStyles | object | * | Custom styles object to override default styles (see the Styles section below). | | labels | object | * | Custom labels for each time unit (see the Labels section below). | | showLabels | boolean | true | Determines if labels should be shown. | | emphasizeLabels | boolean | true | Determines if labels should be emphasized. | | isDoubleLine | boolean | false | Determines if the display should be in double-line mode. |

customStyles (Styles Object)

The customStyles prop is an object that allows you to define specific styles for the timer. You can override the default styles by providing values for the following properties:

| Property | Type | Default Value | Description | |--------------------------|----------|---------------|--------------------------------| | labelBg | string | #1f2937 | Background color for labels. | | labelColor | string | #f9fafb | Text color for labels. | | labelFontSize | string | 0.6875rem | Font size for labels. | | labelPaddingY | string | 0.3rem | Vertical padding for labels. | | fontFamily | string | sans-serif | Font family for the component. | | separatorColor | string | #1f2937 | Color for separators. | | verticalSeparatorColor | string | #1f2937 | Color for vertical separators. | | digitBg | string | #1f2937 | Background color for digits. | | digitColor | string | #f9fafb | Text color for digits. | | digitFontSize | string | 0.875rem | Font size for digits. | | digitWidth | string | 1.75rem | Width of each digit. | | digitHeight | string | 2rem | Height of each digit. |

displayUnitsConfig (Units Object)

| Property | Type | Default | Description | |-----------|---------|---------|--------------------------------------| | years | boolean | true | Show the years unit in the ticker. | | months | boolean | true | Show the months unit in the ticker. | | days | boolean | true | Show the days unit in the ticker. | | hours | boolean | true | Show the hours unit in the ticker. | | minutes | boolean | true | Show the minutes unit in the ticker. | | seconds | boolean | true | Show the seconds unit in the ticker. |

labels (Labels Object)

The labels prop is an object that allows you to provide custom labels for each time unit. The object can include the following properties:

| Property | Type | Description | |-----------|----------|-------------------------------| | years | string | Label for the "years" unit. | | months | string | Label for the "months" unit. | | days | string | Label for the "days" unit. | | hours | string | Label for the "hours" unit. | | minutes | string | Label for the "minutes" unit. | | seconds | string | Label for the "seconds" unit. |

Customizing Timer Behavior

You can pass a custom function using the onTimesUp prop, which is triggered when the countdown reaches zero. This allows you to implement any custom logic, such as redirecting the user, showing a message, or starting a new countdown.

<TimeTicker
  initialSeconds={1800} // 30 minutes
  onTimesUp={() => {
    console.log('Countdown finished!');
    // Custom behavior here
  }}
/>

Demo

You can view a live demo of the React Time Ticker component here.

Changelog

[1.0.0] - YYYY-MM-DD

• Initial release of the TimeTicker component with core features:
  • Time unit configuration (years, months, days, hours, minutes, seconds).
  • Customizable styles for digits, labels, and separators.
  • Optional onTimesUp callback function.
  • Configuration to show/hide time units (e.g., hide years or months).
  • Support for double-line layout and label emphasis.

Contributing

Feel free to open issues and submit pull requests on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.