timescape

timescape is a headless library, meaning it manages the complex logic of date and time manipulation, accessibility (ARIA spinbutton roles, keyboard navigation), and state, while leaving the UI/styling entirely to you.

To build a component, you use framework-specific hooks or managers that provide 'getters' or 'props' for a root container and individual input fields (e.g., years, months, days, hours, minutes, seconds). You decide the order and visual presentation by how you render these elements in your markup.

$NOW is a special constant used for minDate and maxDate. It represents the current date and time at the moment of user interaction and dynamically adjusts itself, so you do not need to manually update it to keep constraints current.

Import it based on your framework:

• Core/Generic: import { $NOW } from "timescape";
• React/Preact: import { $NOW } from "timescape/react";
• Svelte: import { NOW } from "timescape/svelte"; (Note: prefix removed for Svelte compatibility)

import { $NOW } from "timescape";

// Example usage in options
const options = {
  minDate: $NOW
};

In v0.9+, useTimescape no longer returns the options object or update function. Use createSignal to manage the date and pass the signal value to the date prop, updating the signal within onDateChange.

const [date, setDate] = createSignal(new Date());
const { getInputProps, getRootProps } = useTimescape({
  date: date(),
  onDateChange: (nextDate) => {
    setDate(nextDate);
  },
});

// To update the date externally:
setDate(new Date());

In versions prior to v0.9, the useTimescape hook returned an options object and an update function. In v0.9+, these have been removed. You must now manage the date state yourself using useState and pass it back into the hook via date and onDateChange.

// After v0.9 migration
const [date, setDate] = useState<Date | null>(new Date());
const { getRootProps, getInputProps } = useTimescape({
  date,
  onDateChange: (nextDate) => {
    console.log("Date changed to", nextDate);
    setDate(nextDate);
  },
});

// To update the date externally:
setDate(new Date());

In v0.9+, createTimescape no longer returns the options object. Use a writable store to manage the date and pass the current value to the date prop, updating the store within onDateChange.

<script>
const date = writable(new Date());
const { inputProps, rootProps } = createTimescape({
  date: $date,
  onDateChange: (nextDate) => {
    date.set(nextDate);
  },
});

// To update the date externally:
date.set(new Date());
</script>

You can install timescape using your preferred package manager. The library is lightweight (~5.3 kB min+gzip for the core) and has no runtime dependencies.

# pnpm
pnpm add timescape

# yarn
yarn add timescape

# npm
npm install --save timescape

Timescape intercepts keydown events to enhance input behavior. To handle your own keydown events and prevent timescape from processing them, attach your handler during the capturing phase and call e.preventDefault().

<input
  onKeyDownCapture={(e) => {
    if (e.key === "Enter") {
      e.preventDefault();
    }
  }}
/>

Timescape is unstyled by default. To achieve a standard look, use a flex container for the root and font-variant-numeric: tabular-nums on inputs to ensure consistent widths.

Recommended HTML Structure

<div class="timescape">
  <!-- Date inputs -->
  <input />
  <span class="separator">/</span>
  <input />
  <span class="separator">/</span>
  <input />

  <span class="separator">&nbsp;</span>

  <!-- Time inputs -->
  <input />
  <span class="separator">:</span>
  <input />
  <span class="separator">:</span>
  <input />
</div>

Key CSS Tips

• Use .timescape:focus-within to highlight the entire component when an input is active.
• Set caret-color: transparent on inputs for touch devices where fields might not be readonly.
• Use box-sizing: content-box and border: none; outline: none; on inputs to manage custom focus states easily.

In v0.9+, useTimescape no longer returns the options object. Use a ref to manage the date and pass it to the date prop, updating it via onDateChange.

<script setup>
const date = ref(new Date());
const { registerElement, registerRoot } = useTimescape({
  date,
  onDateChange: (nextDate) => {
    date.value = nextDate;
  },
});

// To update the date externally:
date.value = new Date();
</script>