Advanced Date & Time Input JavaScript Library – Timescape

Timescape is an accessible, headless, touch-enable, user-friendly date & time selector component designed specifically to enhance and replace the native date and time inputs in your applications.  Compatible with popular frameworks like React, Vue, Solid, Preact, and Svelte.

With its flexible API, you can use hooks to get seamless component integration. Plus, you have the freedom to render inputs in any order, ensuring the date/time format fits your application’s needs.

How to use it:

1. Install the Timescape via package managers.

# Yarn
$ yarn add timescape
# NPM
$ npm i timescape

2. Integrate Timescape into your Vue project.

// App.vue
<template>
  <div class="timescape-root" :ref="registerRoot()">
    <input :ref="registerElement('days')" class="timescape-input" />
    <span class="separator">/</span>
    <input :ref="registerElement('months')" class="timescape-input" />
    <span class="separator">/</span>
    <input :ref="registerElement('years')" class="timescape-input" />
    <span class="separator">&nbsp;</span>
    <input :ref="registerElement('hours')" class="timescape-input" />
    <span class="separator">:</span>
    <input :ref="registerElement('minutes')" class="timescape-input" />
    <span class="separator">:</span>
    <input :ref="registerElement('seconds')" class="timescape-input" />
  </div>
</template>
<script lang="ts" setup>
import { useTimescape, $NOW, type UseTimescapeOptions } from 'timescape/vue'
import { ref, computed, watchEffect, reactive } from 'vue'
const date = ref(new Date())
const dateString = computed(() => date.value.toLocaleString('en-UK'))
watchEffect(() => {
  console.log('Date changed to', date.value)
})
const options = reactive({
  date,
} as UseTimescapeOptions)
const { registerElement, registerRoot } = useTimescape(options)
</script>

3. Integrate Timescape into your React project.

// App.tsx
import { useTimescape } from 'timescape/react'
function App() {
  const { getRootProps, getInputProps } = useTimescape({
    date: new Date(),
    onChangeDate: (nextDate) => {
      console.log('Date changed to', nextDate)
    },
  })
  return (
    <div className="timescape-root" {...getRootProps()}>
      <input className="timescape-input" {...getInputProps('days')} />
      <span className="separator">/</span>
      <input className="timescape-input" {...getInputProps('months')} />
      <span className="separator">/</span>
      <input className="timescape-input" {...getInputProps('years')} />
      <span className="separator"> </span>
      <input className="timescape-input" {...getInputProps('hours')} />
      <span className="separator">:</span>
      <input className="timescape-input" {...getInputProps('minutes')} />
      <span className="separator">:</span>
      <input className="timescape-input" {...getInputProps('seconds')} />
    </div>
  )
}
export default App

4. All possible options.

export type Options = {
  date?: Date;
  minDate?: Date | $NOW;
  maxDate?: Date | $NOW;
  hour12?: boolean;
  digits?: "numeric" | "2-digit";
  wrapAround?: boolean;
  snapToStep?: boolean;
  wheelControl?: boolean;
  disallowPartial?: boolean;
};

Changelog:

v0.8.0 (08/16/2024)

• Add support for milliseconds
• Added ampm to all integration hooks with methods for custom AM/PM controls.

v0.7.1 (12/26/2024)

• Export STOP_EVENT_PROPAGATION

v0.7.0 (11/22/2024)

• Added disallowPartial option

v0.6.2 (11/12/2024)

• Added the ability to prevent the default keydown event handling. If you want to handle keydown events yourself, you can now prevent the default behavior by using onKeyDownCapture (or the equivalent in your framework) and calling preventDefault() in your handler.

v0.6.1 (10/08/2024)

• Skip number inputs when meta/ctrl is pressed.

v0.5.2 (09/30/2024)

• adding cjs output format

v0.5.1 (08/19/2024)

• Maintain correct AM/PM value when changing hours in hour12 mode

v0.5.0 (07/30/2024)

• Allow native key events to be passed through in the keydown

v0.4.4 (07/19/2024)

• Allow switching AM/PM on mobile

v0.4.3 (05/18/2024)

• Bugfix

v0.4.1 (03/05/2024)

• Fix leaky shadow elements

v0.4.0 (12/19/2023)

• timescape now supports ranges for the date/time inputs.