TimerComponent Documentation

Overview

TimerComponent is a customizable web component package that provides a countdown timer with play, pause, and reset functionalities. This package includes four main web components: TimerComponent, TimerPlayerComponent, TimerPartComponent.

Installation

Install the package via NPM:

npm install @ibrahimjs/timer-component

Usage

Importing Components

To use the components in your project, import them as follows as create customElements with them:

    import { TimerComponent } from "@ibrahimjs/timer-component";
    import { TimerPlayerComponent } from "@ibrahimjs/timer-component";
    import { TimerPartComponent } from "@ibrahimjs/timer-component";

    window.customElements.define("timer-component", TimerComponent);
    window.customElements.define("timer-player-component", TimerPlayerComponent);
    window.customElements.define("timer-part-component", TimerPartComponent);

TimerComponent

TimerComponent is the core component that handles the countdown timer functionality.

Properties

• start (Number): Initial countdown value in seconds. Default is 0.
• limit (Number): Countdown limit value in seconds. Required when reverse is false.
• reverse (Boolean): If true, the timer counts down. Default is false.
• autostart (Boolean): If true, the timer starts automatically. Default is false.
• autoreset (Boolean): If true, the timer resets automatically when finished. Default is false.

Example

<timer-component
  start="0"
  limit="10"
  reverse
  autostart
  autoreset
></timer-component>

TimerPlayerComponent

TimerPlayerComponent provides controls to play, pause, and reset the TimerComponent.

Properties

• playBtn (Boolean): Displays the play button. Default is false.
• pauseBtn (Boolean): Displays the pause button. Default is false.
• resetBtn (Boolean): Displays the reset button. Default is false.
• isFinishedMessage (String): Message displayed when the timer finishes. Default is "¡Finish!".

Example

<timer-player-component
  play-btn
  pause-btn
  reset-btn
  finish-message="Ready!"
>
  <timer-component></timer-component>
</timer-player-component>

TimerPartComponent

TimerPartComponent displays individual parts of the timer (days, hours, minutes, seconds).

Properties

• value (Number): The numeric value of the time part.
• format (String): The format of the time part (DD, HH, MM, SS).

Example

<timer-part-component value="12" format="HH"></timer-part-component>

SetTimerComponent

SetTimerComponent provides an input for updating the TimerComponent dynamically.

Properties

• inputValue (Number): The input value in seconds. Default is 0.

Events

• submit-timer: Dispatched when the timer value is submitted. Includes the new timer value in the detail.

Styling

Each component can be customized using CSS variables for better integration with your design system.

TimerComponent Styles

• --timer-component-part-color: Color of the timer parts.
• --timer-component-join-padding: Padding between the timer parts.

TimerPlayerComponent Styles

• --timer-player-component-action-margin: Margin for action buttons.
• --timer-player-component-status-margin: Margin for the status display.
• --timer-player-component-status-color: Color for the status display.
• --timer-player-component-status-font-size: Font size for the status display.
• --timer-player-component-button-padding: Padding for action buttons.
• --timer-player-component-button-margin: Margin for action buttons.
• --timer-player-component-button-border-radius: Border radius for action buttons.
• --timer-player-component-button-border: Border style for action buttons.
• --timer-player-component-color: Text color for action buttons.
• --timer-player-component-part-color: Background color for action buttons.
• --timer-player-component-play-color: Text color for the play button.
• --timer-player-component-play-background-color: Background color for the play button.

TimerPartComponent Styles

• --timer-component-part-color: Text color for timer parts.
• --timer-component-part-padding: Padding for timer parts.
• --timer-component-part-box-shadow: Box shadow for timer parts.
• --timer-component-part-border-radius: Border radius for timer parts.

Events

• isFinished: Dispatched by TimerComponent when the timer finishes.

License

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