# semantic-duration-input

> Vue 3 input component that parses human-friendly durations ("2h", "3 days", "1h30", "1:30", "PT1H30M") into minutes, seconds, milliseconds or ISO 8601, plus a framework-free parser and formatter.

Key facts:

- Needs Vue 3.5+. Install with `npm install semantic-duration-input` and use `import { DurationInput } from 'semantic-duration-input'`.
- `v-model` holds whole minutes by default, and `null` when the field is empty. `valueFormat` switches it to `'seconds'`, `'ms'`, `'iso'` (`'PT1H30M'`) or a custom `{ toModel, fromModel }`.
- Numeric `min`, `max`, `step` and `presets` are in the model's unit. Duration text such as `'8h'` works with every format.
- The core functions work in seconds: `parseDuration` returns `{ ok: true, seconds, minutes }` or `{ ok: false, error, token?, index?, suggestion? }`, and `formatDuration`, `toIso` and the `min`/`max` parse options take seconds. They are also exported without Vue from `semantic-duration-input/core`.
- Built-in locales: `en` and `de` are accepted by default. `es`, `fr`, `pt`, `hi`, `ar` and `zh` are exported too and must be passed in `locales` (e.g. `:locales="[fr, en]"`); the first one, or the `locale` prop, sets the language of the normalized text and error messages.
- A bare number (`45`) is a `missing_unit` error unless `defaultUnit` is set. Seconds (`30s`) are only accepted with `precision="second"`.
- Error codes: `empty`, `invalid_format`, `unknown_unit`, `missing_unit`, `out_of_range`.
- Styles: with Tailwind v4, `@import 'semantic-duration-input/tailwind.css';` after `@import 'tailwindcss';`. Without Tailwind, `import 'semantic-duration-input/style.css'`. Neither is needed when rendering another input with `as` or through the renderless default slot.
- UI libraries: `:as="Input"` renders shadcn-vue, Nuxt UI, Vuetify or PrimeVue inputs, with the `nuxtUi`, `vuetify` and `primevue` presets for `invalid-props`.
- Nuxt: add `'semantic-duration-input/nuxt'` to `modules`. It auto-imports the component and adds the stylesheet.
- Forms: `name` submits the model value through a hidden input. `durationSchema()` is a Standard Schema for Valibot, ArkType, TanStack Form, VeeValidate and others.

The whole documentation is in [llms-full.txt](https://nicoalbrecht.github.io/semantic-duration-input/llms-full.txt). The npm package ships both files for its version in `node_modules/semantic-duration-input/dist/`.

## Guide

- [Getting started](https://nicoalbrecht.github.io/semantic-duration-input/guide/getting-started.md): Install the package, add the styles, bind v-model and register the plugin.
- [Syntax](https://nicoalbrecht.github.io/semantic-duration-input/guide/syntax.md): What the parser accepts. Units, compound values, implicit units, decimals, clock format, ISO 8601, typo suggestions and error codes.
- [Behaviour](https://nicoalbrecht.github.io/semantic-duration-input/guide/behaviour.md): When v-model updates, when errors are shown (validateOn), the preview, keyboard stepping, snapping, clamping and presets.
- [Value formats](https://nicoalbrecht.github.io/semantic-duration-input/guide/value-formats.md): Store minutes, seconds, milliseconds, ISO 8601 strings or a custom format in v-model.
- [Locales](https://nicoalbrecht.github.io/semantic-duration-input/guide/locales.md): Built-in languages (English, German, Spanish, French, Portuguese, Hindi, Arabic, Chinese), the display style and units, and custom locales with defineLocale.
- [Custom units](https://nicoalbrecht.github.io/semantic-duration-input/guide/units.md): Units of your own (sprint, pomodoro) and working-time days and weeks with customUnits.
- [Forms and validation](https://nicoalbrecht.github.io/semantic-duration-input/guide/forms.md): Native form submission, required, min and max, validate() on submit, error messages, and durationSchema for Standard Schema libraries and Zod.
- [Styling](https://nicoalbrecht.github.io/semantic-duration-input/guide/styling.md): Sizes, variants, the --sdi-* design tokens, classes per part through ui, unstyled mode and the tailwind-variants theme.
- [Integrations](https://nicoalbrecht.github.io/semantic-duration-input/guide/integrations.md): Render shadcn-vue, Nuxt UI, Vuetify, PrimeVue or any other input with as, the renderless slot, and app-wide defaults.
- [Nuxt](https://nicoalbrecht.github.io/semantic-duration-input/guide/nuxt.md): The Nuxt module and its options.
- [Headless usage](https://nicoalbrecht.github.io/semantic-duration-input/guide/headless.md): The Vue-free core entry for Node and the browser, and the useDurationInput composable.

## Reference

- [Component](https://nicoalbrecht.github.io/semantic-duration-input/reference/component.md): Props, attributes, events, slots, exposed methods, plugin and types of DurationInput.
- [Core API](https://nicoalbrecht.github.io/semantic-duration-input/reference/core.md): parseDuration, formatDuration, formatErrorMessage, durationSchema, ISO 8601 and model value helpers, locales, constants and types.

## Optional

- [Migrating to 0.2](https://nicoalbrecht.github.io/semantic-duration-input/migration/0.2.md): Breaking changes from 0.1 to 0.2.
- [Changelog](https://github.com/nicoalbrecht/semantic-duration-input/blob/main/CHANGELOG.md): Release notes for every version.