Skip to content

Latest commit

 

History

History
209 lines (164 loc) · 11.2 KB

README.md

File metadata and controls

209 lines (164 loc) · 11.2 KB
Raw

react-flip-clock-countdown

A 3D animated countdown component for React.

NPM JavaScript Style Guide

react flip clock countdown demo

Install

npm install --save @leenguyen/react-flip-clock-countdown

Or

yarn add @leenguyen/react-flip-clock-countdown

Props

The FlipClockCountdown has all properties of div and additional props below

Name Type Required Default Description
to Date|string|number yes Date or timestamp in the future.
containerProps object no undefined Props apply to the flip clock container. This prop is deprecated, you should apply directly to the FlipClockCountdown component.
onComplete func no Callback when countdown ends
Signature:
function() => void
onTick func no Callback on every interval tick
Signature:
function({ timeDelta, completed }) => void
renderMap Array<boolean> no [true, true, true, true] Each element represents the render state of each section (day, hour, minute, second). If true section will be rendered, false otherwise.
labels Array<string> no ['Days', 'Hours', 'Minutes', 'Seconds'] Custom array of labels used to represent information for each section (day, hour, minute, second).
showLabels boolean no true Set it to false if you don't want to show the labels.
showSeparators boolean no true Set it to false if you don't want to show the separators (colon) between time unit.
labelStyle React.CSSProperties no undefined The styles apply to labels font-size, color, width, height, etc.
digitBlockStyle React.CSSProperties no undefined The styles apply to digit blocks like font-size, color, width, height, etc.
separatorStyle object no undefined The styles apply to separator (colon), includes size and color.
dividerStyle object no undefined The style will be applied to divider, includes color and height.
spacing object no undefined This prop allows you to modify the clock spacing.
duration number no 0.7 Duration (in second) when flip card. Valid value in range (0, 1).
hideOnComplete boolean no true By default, the countdown will be hidden when it completed (or show children if provided). This will keep the timer in place and stuck at zeros when the countdown is completed.
stopOnHiddenVisibility boolean no false Whether or not to stop the clock when the visibilityState is hidden, enabling this feature will prevent the component gets derailed if we switch between browser tabs.
renderOnServer boolean no false Whether or not to render the clock on server.

Usage

Basic usage

import React, { Component } from 'react';

import FlipClockCountdown from '@leenguyen/react-flip-clock-countdown';
import '@leenguyen/react-flip-clock-countdown/dist/index.css';

class Example extends Component {
  render() {
    return <FlipClockCountdown to={new Date().getTime() + 24 * 3600 * 1000 + 5000} />;
  }
}

Render a React Component when countdown is complete

In case you want to change the output of the component, or want to signal that the countdown's work is done, you can do this by either using the onComplete callback or by specifying a React child within <FlipClockCountdown></FlipClockCountdown>, which will only be shown once the countdown is complete.

import React, { Component } from 'react';

import FlipClockCountdown from '@leenguyen/react-flip-clock-countdown';
import '@leenguyen/react-flip-clock-countdown/dist/index.css';

class Completed extends Component {
  render() {
    return <span>The countdown is complete</span>
  }
}

class RenderByUsingReactChild extends Component {
  render() {
    return (
      <FlipClockCountdown to={new Date().getTime() + 24 * 3600 * 1000 + 5000}>
        <Completed />
      </FlipClockCountdown>;
    )
  }
}

class RenderByUsingCallback extends Component {
  constructor(props) {
    super(props);

    this.endTime = new Date().getTime() + 24 * 3600 * 1000 + 5000;
    this.state = {
      isCompleted: false
    }

    this.handleComplete = this.handleComplete.bind(this);
  }

  handleComplete() {
    this.setState({ isCompleted: true });
  }

  render() {
    return (
      <React.Fragment>
        {isCompleted && <Completed />}
        <FlipClockCountdown onComplete={this.handleComplete} to={this.endTime} />
      </React.Fragment>
    )
  }
}

Render a custom countdown

Custom styles

class Example extends Component {
  render() {
    return (
      <FlipClockCountdown
        to={new Date().getTime() + 24 * 3600 * 1000 + 5000}
        labels={['DAYS', 'HOURS', 'MINUTES', 'SECONDS']}
        labelStyle={{ fontSize: 10, fontWeight: 500, textTransform: 'uppercase' }}
        digitBlockStyle={{ width: 40, height: 60, fontSize: 30 }}
        dividerStyle={{ color: 'white', height: 1 }}
        separatorStyle={{ color: 'red', size: '6px' }}
        duration={0.5}
      >
        Finished
      </FlipClockCountdown>
    );
  }
}

Custom styles via css

import 'styles.css';

class Example extends Component {
  render() {
    return <FlipClockCountdown to={new Date().getTime() + 24 * 3600 * 1000 + 5000} className='flip-clock' />;
  }
}
/* styles.css */

.flip-clock {
  --fcc-flip-duration: 0.5s; /* transition duration when flip card */
  --fcc-spacing: 8px; /* space between unit times and separators */
  --fcc-digit-block-width: 40px; /* width of digit card */
  --fcc-digit-block-height: 60px; /* height of digit card, highly recommend in even number */
  --fcc-digit-block-radius: 5px; /* border radius of digit card */
  --fcc-digit-block-spacing: 5px; /* space between blocks in each unit of time */
  --fcc-digit-font-size: 30px; /* font size of digit */
  --fcc-digit-color: white; /* color of digit */
  --fcc-label-font-size: 10px; /* font size of label */
  --fcc-label-color: #ffffff; /* color of label */
  --fcc-background: black; /* background of digit card */
  --fcc-divider-color: white; /* color of divider */
  --fcc-divider-height: 1px; /* height of divider */
  --fcc-separator-size: 6px; /* size of colon */
  --fcc-separator-color: red; /* color of colon */
}

Custom section to be rendered

In case you don't want to display the date, use renderMap to custom render state of each section

class Example extends Component {
  render() {
    return (
      <FlipClockCountdown to={new Date().getTime() + 24 * 3600 * 1000 + 5000} renderMap={[false, true, true, true]}>
        Finished
      </FlipClockCountdown>
    );
  }
}

Contributing

The package is made up of 2 main folders:

  • /src contains the FlipClockCountdown
  • /examples contains the create-react-app and create-next-app based demo website

To setup and run a local copy:

  1. Clone this repo with https://github.com/sLeeNguyen/react-flip-clock-countdown
  2. Run npm install in the root folder
  3. Run npm install in the examples/react-app folder
  4. In separate terminal windows, run npm start in the root and examples/react-app folders.

When you're done working on your changes, feel free to send PRs with the details and include a screenshot if you've changed anything visually.

License

MIT © leenguyen