Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

DateTimePicker

One date and time field with a shared calendar and time selection panel.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add date-time-picker

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import DateTimePicker from './components/ui/date-time-picker/DateTimePicker.vue'

const startsAt = ref('2026-10-02T14:30')
</script>

<template>
  <div class="w-full max-w-xl">
    <DateTimePicker
      v-model="startsAt"
      aria-label="Event start"
      min="2026-10-01T09:00"
      max="2026-10-08T18:00"
      :step="900"
    />
  </div>
</template>

The model and native form value are one local YYYY-MM-DDTHH:mm string. The component deliberately does not invent a timezone or convert to an instant.

When to use it

Appointment

Choose a date and stepped local time within one bounded interval.

Event start

Collect a wall-clock date and time before applying a separately chosen timezone.

More examples

Bounded appointment

Boundary dates automatically constrain the available times.

Bounded appointment
<script setup lang="ts">
import { ref } from 'vue'
import DateTimePicker from './components/ui/date-time-picker/DateTimePicker.vue'

const appointment = ref('2026-10-12T09:30')
</script>

<template>
  <DateTimePicker
    v-model="appointment"
    name="appointment"
    min="2026-10-12T08:00"
    max="2026-10-12T18:00"
    :step="900"
    aria-label="Appointment"
  />
</template>

Localized picker

Override only the English labels your application needs.

Localized picker
<script setup lang="ts">
import { ref } from 'vue'
import DateTimePicker from './components/ui/date-time-picker/DateTimePicker.vue'

const startsAt = ref('2026-10-12T14:30')
</script>

<template>
  <DateTimePicker
    v-model="startsAt"
    locale="fr-LU"
    aria-label="Début"
    :locale-text="{
      chooseDateTime: 'Choisir la date et l’heure',
      dateTimePickerLabel: 'Choisir la date et l’heure',
      clearSelection: 'Effacer la date et l’heure',
      dateLabel: 'Date',
      timeLabel: 'Heure',
      date: { nextMonth: 'Mois suivant', previousMonth: 'Mois précédent' },
      time: { clearSelection: 'Effacer l’heure' },
    }"
  />
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

DateTimePicker

Complete API for DateTimePicker
NameType or signatureDefaultWhat it does
referenceDatepropstring | undefinedNot setStable date used to decide which month or year appears first.
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
namepropstring | undefinedNot setName used when this control submits a value with a form.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
readonlypropboolean | undefinedNot setShow the value while preventing edits.
requiredpropboolean | undefinedNot setAsk the browser to require a value before form submission.
minpropstring | undefinedNot setSmallest allowed value.
maxpropstring | undefinedNot setLargest allowed value.
steppropnumber | undefined60Amount added or removed for each adjustment.
localepropstring | undefinedNot setChoose the language and regional formatting for dates or text.
firstDayOfWeekprop0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined1Choose which weekday begins each calendar row.
localeTextpropDateTimePickerLocaleTextOverrides | undefinedNot setControls the locale text behavior of DateTimePicker.
modelValuemodelstring | undefined""Current value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: string]—Requests a new model value from the parent.
errorslot((props: { message: string; messages: string[]; }) => unknown) | undefinedOptionalContent for the error area of DateTimePicker.
elementexposedHTMLInputElement | null—Reference to the underlying HTML element.
triggerElementexposedHTMLButtonElement | null—Access trigger element from a component template ref.
dateElementexposedHTMLInputElement | null—Access date element from a component template ref.
timeElementexposedHTMLInputElement | null—Access time element from a component template ref.
focusexposed() => void | undefined—Move keyboard focus to this control.
showPickerexposed() => void—Access show picker from a component template ref.
openexposed() => void—Open this component from application code.
closeexposed(restoreFocus?: boolean) => void—Close this component from application code.
clearexposed() => void—Access clear from a component template ref.
Public type definitions
Public types
// packages/frameworks/vue/components/date-time-picker/types.ts
import type { ControlSize } from '@getweini/vue/types'

export interface DateTimePickerLocaleText {
  chooseDateTime?: string
  dateTimePickerLabel?: string
  clearSelection?: string
  dateLabel: string
  timeLabel: string
  date: {
    calendarLabel: string
    previousMonth: string
    nextMonth: string
    chooseDate: string
    clearSelection: string
  }
  time: {
    timePickerLabel: string
    chooseTime: string
    hoursLabel: string
    minutesLabel: string
    secondsLabel: string
    clearSelection: string
  }
}

export type DateTimePickerLocaleTextOverrides = Partial<
  Omit<DateTimePickerLocaleText, 'date' | 'time'>
> & {
  date?: Partial<DateTimePickerLocaleText['date']>
  time?: Partial<DateTimePickerLocaleText['time']>
}

export interface DateTimePickerProps {
  referenceDate?: string
  id?: string
  name?: string
  form?: string
  size?: ControlSize
  invalid?: boolean
  disabled?: boolean
  readonly?: boolean
  required?: boolean
  min?: string
  max?: string
  step?: number
  locale?: string
  firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6
  localeText?: DateTimePickerLocaleTextOverrides
}


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • Store an IANA timezone separately when the value represents an event that must become an instant.
  • The combined model updates only after both a date and a time are present.

Accessibility and localization

  • Give the single trigger a visible label or accessible name. Its shared panel contains labelled calendar and time groups; Escape returns focus to the trigger.

Source contract and editing guidance