{"id":21033170,"url":"https://github.com/josephuspaye/timer","last_synced_at":"2026-04-18T17:36:43.767Z","repository":{"id":116943019,"uuid":"289799446","full_name":"JosephusPaye/timer","owner":"JosephusPaye","description":"A small and smooth (60-fps) countdown timer and stopwatch for Vue and vanilla JS","archived":false,"fork":false,"pushed_at":"2020-08-24T10:49:00.000Z","size":351,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-29T19:47:49.478Z","etag":null,"topics":["countdown","createweekly","javascript","realtime","stopwatch","timer","vue"],"latest_commit_sha":null,"homepage":"https://timerlib.netlify.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JosephusPaye.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-24T01:33:57.000Z","updated_at":"2023-09-12T20:47:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"38bd6ce3-aec5-4999-baea-ab5d22b99188","html_url":"https://github.com/JosephusPaye/timer","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/JosephusPaye/timer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JosephusPaye%2Ftimer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JosephusPaye%2Ftimer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JosephusPaye%2Ftimer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JosephusPaye%2Ftimer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JosephusPaye","download_url":"https://codeload.github.com/JosephusPaye/timer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JosephusPaye%2Ftimer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31978515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T17:30:12.329Z","status":"ssl_error","status_checked_at":"2026-04-18T17:29:59.069Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["countdown","createweekly","javascript","realtime","stopwatch","timer","vue"],"created_at":"2024-11-19T12:52:23.039Z","updated_at":"2026-04-18T17:36:43.727Z","avatar_url":"https://github.com/JosephusPaye.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Timer\n\n⏳ A small and smooth (60-fps) countdown timer and stopwatch for Vue and vanilla JS.\n\nThis project is part of [#CreateWeekly](https://dev.to/josephuspaye/createweekly-create-something-new-publicly-every-week-in-2020-1nh9), my attempt to create something new publicly every week in 2020.\n\n## Demo\n\n\u003chttps://timerlib.netlify.app\u003e\n\n## Installation\n\n```\nnpm install @josephuspaye/timer --save\n```\n\n## Usage\n\n### JS\n\nThe following creates a 15-second countdown timer without a user interface:\n\n```js\nimport { Timer } from '@josephuspaye/timer';\n\nconst timer = new Timer('countdown', 10 * 1000); // change 'countdown' to 'stopwatch' for a stopwatch\n\ntimer.on('tick', (ms) =\u003e {\n    console.log('event: tick', ms);\n});\ntimer.on('done', () =\u003e {\n    console.log('event: done');\n});\ntimer.on('state', (state) =\u003e {\n    console.log('event: state', state);\n});\n\ntimer.start();\n```\n\n### Vue: default template\n\nYou can create a timer with the default template, which shows days, hours, minutes, seconds, and milliseconds. You can also use the following classes to style the resulting timer:\n\n-   `timer` - added to the timer root element (a `div` element). `is-done` is appended when the timer reaches its length, and `is-overflowed` is appended when it exceeds its length.\n-   `timer__delimiter` - added to the `:` delimiters (`span` elements)\n-   `timer__days` - added to the timer days (a `span` element)\n-   `timer__hours` - added to the timer hours (a `span` element)\n-   `timer__seconds` - added to the timer seconds (a `span` element)\n-   `timer__milliseconds` - added to the timer milliseconds (a `span` element)\n\nThe following creates a simple 15-second countdown timer that starts automatically ([view on CodePen](https://codepen.io/JosephusPaye/pen/wvGgyNz)):\n\n```vue\n\u003ctemplate\u003e\n    \u003cdiv\u003e\n        \u003cTimer type=\"countdown\" autoStart :length=\"15 * 1000\" /\u003e\n        \u003c!-- change the above to `type=\"stopwatch\"` for a stopwatch --\u003e\n    \u003c/div\u003e\n\u003c/template\u003e\n\n\u003cscript\u003e\nimport { TimerVue as Timer } from '@josephuspaye/timer';\n\nexport default {\n    components: { Timer },\n};\n\u003c/script\u003e\n```\n\n### Vue: custom template\n\nYou can use a [scoped slot](https://vuejs.org/v2/guide/components-slots.html#Scoped-Slots) to render your own template.\n\nThe following renders a custom template with 15-second stopwatch that starts automatically and allows for overflow ([view on CodePen](https://codepen.io/JosephusPaye/pen/MWyJQMV)):\n\n```vue\n\u003ctemplate\u003e\n    \u003cdiv\u003e\n        \u003cTimer\n            type=\"stopwatch\"\n            auto-start\n            allow-overflow\n            :length=\"15 * 1000\"\n            v-slot=\"{ time, isDone, isOverflowed }\"\n        \u003e\n            \u003c!-- change the above to `type=\"countdown\"` for a countdown timer --\u003e\n            \u003cdiv\u003e\n                \u003cspan :class=\"{ 'is-overflowed': isOverflowed }\"\u003e\n                    \u003cspan\u003e{{ time.d }}d\u003c/span\u003e\n                    \u003cspan\u003e{{ time.h }}h\u003c/span\u003e\n                    \u003cspan\u003e{{ time.m }}m\u003c/span\u003e\n                    \u003cspan\u003e{{ time.s }}s\u003c/span\u003e\n                    \u003cspan\u003e{{ time.ms }}ms\u003c/span\u003e\n                \u003c/span\u003e\n\n                \u003cspan\u003e{{ isDone ? '✅' : '⏳' }}\u003c/span\u003e\n            \u003c/div\u003e\n        \u003c/Timer\u003e\n    \u003c/div\u003e\n\u003c/template\u003e\n\n\u003cscript\u003e\nimport { TimerVue as Timer } from '@josephuspaye/timer';\n\nexport default {\n    components: { Timer },\n};\n\u003c/script\u003e\n\n\u003cstyle\u003e\n.is-overflowed {\n    color: red;\n}\n\u003c/style\u003e\n```\n\n## JS API\n\nThe `Timer` class can be used to create a timer without a user interface.\n\n### Properties and methods\n\nCreate a timer using `const timer = new Timer(type, options)` and call methods using `timer.method()`.\n\n```ts\n/**\n * The type of timer: 'countdown' or 'stopwatch'\n */\nexport declare type TimerType = 'countdown' | 'stopwatch';\n\n/**\n * The timer state, one of 'stopped', 'running', 'paused'\n */\nexport declare type TimerState = 'stopped' | 'running' | 'paused';\n\n/**\n * Timer constructor options\n */\nexport interface TimerOptions {\n    /**\n     * Whether the timer should allow overflow. If true, the timer will\n     * set `isOverflowed` and continue counting when the length is\n     * reached. Otherwise, the timer stops upon reaching the length.\n     */\n    allowOverflow?: boolean;\n}\n\nexport declare class Timer {\n    /**\n     * The type of timer: 'countdown' or 'stopwatch'\n     */\n    type: TimerType;\n\n    /**\n     * The timer state, one of 'stopped', 'running', 'paused'\n     */\n    state: TimerState;\n\n    /**\n     * Indicates whether the timer allows overflow. When true, the timer\n     * will set `isOverflowed` and continue counting when the length is\n     * reached. Otherwise, the timer stops upon reaching the length.\n     */\n    allowOverflow: boolean;\n\n    /**\n     * Indicates whether the timer has overflowed (i.e. exceeded the length)\n     */\n    isOverflowed: boolean;\n\n    /**\n     * Indicates whether the timer is done (i.e. met or exceeded the length)\n     */\n    isDone: boolean;\n\n    /**\n     * The timer event emitter\n     */\n    events: Emitter;\n\n    /**\n     * Create a new timer\n     *\n     * @param type    The type of timer: 'countdown' or 'stopwatch'\n     * @param length  How long the timer should count down from or count up to\n     * @param options The timer options\n     */\n    constructor(type: TimerType, length: number, options?: TimerOptions);\n\n    /**\n     * The elapsed time in milliseconds. Is zero if the timer is stopped.\n     */\n    get time(): number;\n\n    /**\n     * Set the timer's length. Will stop the timer and reset internal state for a new run.\n     */\n    setLength(length: number): void;\n\n    /**\n     * Reset the timer\n     */\n    reset(): void;\n\n    /**\n     * Start the timer\n     */\n    start(): void;\n\n    /**\n     * Stop the timer\n     */\n    stop(options?: { isDone: boolean }): void;\n\n    /**\n     * Pause the timer\n     */\n    pause(): void;\n\n    /**\n     * Resume the timer\n     */\n    resume(): void;\n\n    /**\n     * Destroy the timer and event listeners\n     */\n    destroy(): void;\n}\n```\n\n### Events\n\nListen for any of the following timer events using `timer.events.on('event', callbackFunction)`:\n\n| Event      | Description                                                                                                                                                        |\n| :--------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `state`    | Emitted when the timer state changes. The handler is called with the new state, one of `stopped`, `running` or `paused`.                                           |\n| `overflow` | Emitted when the timer exceeds its length.                                                                                                                         |\n| `done`     | Emitted when the timer reaches its length.                                                                                                                         |\n| `tick`     | Emitted when the timer advances. The handler is called with the total time elapsed, in milliseconds. When the timer is running, this is emitted 60 times a second. |\n| `reset`    | Emitted when the timer is reset. The handler is called with the time it was reset to, in milliseconds.                                                             |\n| `start`    | Emitted when the timer is started.                                                                                                                                 |\n| `stop`     | Emitted when the timer is stopped.                                                                                                                                 |\n| `pause`    | Emitted when the timer is paused.                                                                                                                                  |\n| `resume`   | Emitted when the timer is resumed.                                                                                                                                 |\n\n## Vue API\n\n### Props\n\n| Prop            | Type    | Default     | Description                                                                                                                   |\n| :-------------- | :------ | :---------- | :---------------------------------------------------------------------------------------------------------------------------- |\n| `type`          | String  | `countdown` | The type of timer. One of `countdown` or `stopwatch`. This value can be changed while the timer is running.                   |\n| `length`        | Number  |             | How long the timer is running for, in milliseconds. Changing this while the timer is running will cause it to stop and reset. |\n| `autoStart`     | Boolean | `false`     | When `true`, the timer will start automatically on mount. Otherwise the `start()` method has to be called to start it.        |\n| `allowOverflow` | Boolean | `false`     | When `true`, the timer will continue when its length is exceeded. Otherwise it will stop upon reaching its length.            |\n\n### Methods\n\n| Event      | Description                                                                                |\n| :--------- | :----------------------------------------------------------------------------------------- |\n| `start()`  | Start the timer.                                                                           |\n| `stop()`   | Stop the timer.                                                                            |\n| `pause()`  | Pause the timer if it's running.                                                           |\n| `resume()` | Resume the timer if it's paused.                                                           |\n| `toggle()` | Toggle the timer. Will start the timer if stopped, pause if running, and resume if paused. |\n| `reset()`  | Stop and reset the timer, for a possible restart.                                          |\n\n### Events\n\n| Event      | Description                                                                                                                                                        |\n| :--------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `state`    | Emitted when the timer state changes. The handler is called with the new state, one of `stopped`, `running` or `paused`.                                           |\n| `overflow` | Emitted when the timer exceeds its length.                                                                                                                         |\n| `done`     | Emitted when the timer reaches its length.                                                                                                                         |\n| `tick`     | Emitted when the timer advances. The handler is called with the total time elapsed, in milliseconds. When the timer is running, this is emitted 60 times a second. |\n| `reset`    | Emitted when the timer is reset. The handler is called with the time it was reset to, in milliseconds.                                                             |\n| `start`    | Emitted when the timer is started.                                                                                                                                 |\n| `stop`     | Emitted when the timer is stopped.                                                                                                                                 |\n| `pause`    | Emitted when the timer is paused.                                                                                                                                  |\n| `resume`   | Emitted when the timer is resumed.                                                                                                                                 |\n\n### Slots\n\n| Slot      | Description                                                                                              |\n| :-------- | :------------------------------------------------------------------------------------------------------- |\n| (default) | The default slot. Can hold any content with a single root element, and is passed the props listed below. |\n\n#### Default slot props\n\n| Prop           | Type    | Description                                                                                                                                                                     |\n| :------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `time`         | Object  | The timer's current time as an object with keys `d` (days), `h` (hours), `m` (minutes), `s` (seconds), and `ms` (milliseconds). Each value is a padded string ready for display. |\n| `timeElapsed`  | Number  | For a countdown, the total time remaining, in milliseconds. For a stopwatch, the total time elapsed, in milliseconds.                                                           |\n| `state`        | String  | The timer's current state, one of `stopped`, `running` or `paused`.                                                                                                             |\n| `isDone`       | Boolean | Whether or not the timer has reached its length.                                                                                                                                |\n| `isOverflowed` | Boolean | Whether or not the timer has exceeded its length.                                                                                                                               |\n\n## Licence\n\n[MIT](LICENCE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosephuspaye%2Ftimer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosephuspaye%2Ftimer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosephuspaye%2Ftimer/lists"}