Date Picker

NbDatePicker lets users select a date via a text input and an optional calendar dropdown. It comes in three types: simple (text only), single (with calendar), and range (start and end dates with calendar).

Simple Date Picker ​

A text-only field for manually entering dates without a calendar dropdown. Useful for memorable dates like birthdays or expiration dates.

Always communicate the expected date format with the label or helper prop. Placeholder text disappears as soon as the user starts typing, so never rely on it alone.

<template>
  <NbDatePicker
    v-model="date"
    type="simple"
    label="Date of birth"
    placeholder="dd/mm/yyyy"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const date = ref<string | null>(null)
</script>

Single Date Picker ​

Combines a text input with a calendar dropdown. Users can type a date or select one from the calendar.

<template>
  <NbDatePicker v-model="date" label="Start date" placeholder="dd/mm/yyyy" />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const date = ref<string | null>(null)
</script>

Date Range Picker ​

Two inputs for selecting a start and end date. Selecting the start date automatically moves focus to the end date input.

<template>
  <NbDatePicker
    v-model="start"
    v-model:end-value="end"
    type="range"
    label="Date range"
    placeholder="Start date"
    end-placeholder="End date"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const start = ref<string | null>(null)
const end = ref<string | null>(null)
</script>

Per-field labels ​

Give each range field its own label with endLabel. When set, label sits above the start field and endLabel above the end field, so screen readers announce each input unambiguously.

<NbDatePicker
  v-model="start"
  v-model:end-value="end"
  type="range"
  label="Start date"
  end-label="End date"
/>

Min and Max Dates ​

Constrain the selectable date range. Dates outside the bounds are visually dimmed in the calendar and cannot be selected, and dates typed into the field are rejected when they fall outside the bounds.

<NbDatePicker
  v-model="date"
  label="Appointment"
  min="2026-04-10"
  max="2026-04-25"
/>

Disabled Dates ​

Beyond min/max, individual dates can be blocked with disabledDates: either an array of ISO strings or a predicate function. Use it for holidays, weekends, or fully booked days. Disabled dates stay keyboard-focusable so their labels remain discoverable, but they cannot be selected.

<template>
  <NbDatePicker
    v-model="date"
    label="Delivery date"
    helper="Weekends are unavailable"
    :disabled-dates="isWeekend"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const date = ref<string | null>(null)

function isWeekend(iso: string): boolean {
  const day = new Date(iso + 'T00:00:00').getDay()
  return day === 0 || day === 6
}
</script>

Validation States ​

Use error or warning props to display validation feedback below the field. error takes precedence over warning, which takes precedence over helper.

<NbDatePicker
  v-model="date"
  label="Departure"
  error="A valid date is required"
/>
<NbDatePicker
  v-model="date"
  label="Return"
  warning="This date falls on a holiday"
/>

Per-field validation (range) ​

In a range picker each field validates independently, so users can see exactly which field needs correction. error/warning mark only the start field; endError/endWarning mark only the end field.

<NbDatePicker
  v-model="start"
  v-model:end-value="end"
  type="range"
  label="Start date"
  end-label="End date"
  end-error="End date must be after the start date"
/>

Helper Text ​

<NbDatePicker v-model="date" label="Invoice date" helper="Format: dd/mm/yyyy" />

Sizes ​

Three sizes matching the rest of the design system: sm (32px), md (40px, default), and lg (48px).

<NbDatePicker v-model="date" label="Small" size="sm" />
<NbDatePicker v-model="date" label="Medium" size="md" />
<NbDatePicker v-model="date" label="Large" size="lg" />

Disabled and Read-only ​

A disabled field cannot be interacted with at all. A read-only field remains focusable and its value can be copied, but it cannot be edited and the calendar does not open.

<NbDatePicker v-model="date" label="Disabled" disabled />
<NbDatePicker v-model="date" label="Read-only" readonly />

Fluid Variant ​

The fluid variant places the label inside the field, matching other fluid-style form controls. Validation feedback appears as an icon in the field header (hover it for the full message), the same behaviour as the fluid NbTextInput.

<NbDatePicker
  v-model="date"
  variant="fluid"
  label="Delivery date"
  placeholder="dd/mm/yyyy"
/>
<NbDatePicker
  v-model="date"
  variant="fluid"
  label="Delivery date"
  error="A valid date is required"
/>

Week Starting on Sunday ​

<NbDatePicker v-model="date" label="Date" :week-start="0" />

Keyboard Navigation ​

The calendar dropdown follows the WAI-ARIA Date Picker Dialog pattern for full keyboard accessibility.

Input field:

Calendar grid:

The calendar header also provides clickable previous/next month (single caret) and previous/next year (double caret) buttons.

Props ​

Events ​

Exposed Methods ​