Forms

DurationField

Number plus unit for a duration that is stored in milliseconds, so a person types 30 and picks seconds while the value stays one number.

import { DurationField } from '@lostgradient/cinder';
formdurationnumeric
01

Overview

Reference usage

DurationField is a number and the unit it is counted in, for a duration the data stores in milliseconds. The person types 30 and picks seconds; the value the page receives is one number, 30000. The unit starts as the largest that shows the stored value as a whole number (90000 reads as 90 seconds, 3600000 as 1 hour) and then follows the person's choice. A value replaced from outside, such as Edit as JSON in SchemaForm, picks the unit again.

Set unitSelectable to false for a setting that always counts in one unit: the unit becomes text inside the number's own frame ("15 seconds") and there is no select. Inside a FormField or SettingRow leave out label, which the row supplies.

SchemaForm renders a numeric property with this field when its schema says it is a duration: format: "duration-ms", unit: "milliseconds", or a name ending in Ms, _ms or Milliseconds. To show a duration read-only, format it with the formatDuration utility instead.

Usage

svelte 
<script lang="ts">
  import { DurationField } from '@lostgradient/cinder';

  let timeout = $state<number | null>(90_000);
</script>

<DurationField id="timeout" label="Timeout" bind:value={timeout} />
Live preview

Number plus unit

seconds

Stored as 90000 ms and 15000 ms.

02

When to use

Use when
  • A setting or schema field holds a length of time in milliseconds and the person should not have to count zeros.
  • A setting always counts in one unit and should show it beside the number ("30 seconds") — set `unitSelectable` to `false`.
Avoid when
  • Collecting a clock time or a calendar date — use time-field or date-picker.
  • Showing a duration read-only — format it with `formatDuration`.
03

Examples

Number plus unit

A duration stored in milliseconds, typed as a number in the unit that fits it (here 90 seconds). A setting that always counts in one unit fixes it as text inside the frame: "15 seconds".

04

Props

Props for duration-field
Name
Type
Default
Description
id required text Unique identifier for the number input. The unit select takes ${id}-unit.
value bindable number null The duration in milliseconds, or null when the field is empty. Bindable.
onValueChange ((next: number | null) => void)undefined Called with the next duration in milliseconds, or null when the number is cleared or unparseable.
label text Visible label. Omit inside a FormField or SettingRow, which supplies the label.
description text Helper text announced with the field.
error text Validation error; marks the field invalid.
required boolean false Marks the field required.
disabled boolean false Disables the number and the unit.
name text Form field name for the number as typed (in the shown unit).
integer boolean false Rounds the stored milliseconds to whole numbers, for a schema of type integer.
units DurationUnit[] The units on offer, smallest first. The default is milliseconds, seconds, minutes and hours.
unit bindable text The unit the number is shown in, by its value. Starts as the largest unit that shows the value as a whole number, and follows the person's choice. Bindable.
unitSelectable boolean true Whether the person can change the unit. When false the unit is fixed text inside the field's frame ("30 seconds"), as a setting that always counts in seconds draws it.
onblur HTMLInputAttributes['onblur']undefined Called when the number loses focus.