N Date Picker

n-date-picker Component

The n-date-picker component is a comprehensive date selection component that supports multiple date types including date, datetime, date range, month, year, quarter, and week. It offers extensive customization for formatting, validation, shortcuts, and panel behavior.

When to Use

Use n-date-picker when you need to:

• Collect date or datetime input from users
• Select date ranges for filtering or scheduling
• Choose months, years, quarters, or weeks
• Format dates in specific patterns
• Disable specific dates or time ranges
• Provide quick selection shortcuts
• Integrate with forms for date validation

Basic Usage

Date Picker

<template>
  <n-date-picker v-model:value="timestamp" type="date" />
</template>

<script setup>
import { ref } from 'vue'

const timestamp = ref(null)
</script>

DateTime Picker

<template>
  <n-date-picker v-model:value="timestamp" type="datetime" clearable />
</template>

Date Range Picker

<template>
  <n-date-picker v-model:value="range" type="daterange" clearable />
</template>

<script setup>
import { ref } from 'vue'

const range = ref([null, null])
</script>

Different Sizes

<template>
  <n-space vertical>
    <n-date-picker v-model:value="timestamp" size="small" type="date" />
    <n-date-picker v-model:value="timestamp" size="medium" type="date" />
    <n-date-picker v-model:value="timestamp" size="large" type="date" />
  </n-space>
</template>

API Reference

General Props

Date Type Props

DateTime Type Props

DateRange Type Props

Events

Slots

Methods

Common Patterns

Formatted Value Binding

<template>
  <n-date-picker
    v-model:formatted-value="formattedValue"
    value-format="yyyy-MM-dd HH:mm:ss"
    type="datetime"
    clearable
  />
</template>

<script setup>
import { ref } from 'vue'

const formattedValue = ref(null)
</script>

Date Range with Shortcuts

<template>
  <n-date-picker
    v-model:value="range"
    type="daterange"
    :shortcuts="shortcuts"
  />
</template>

<script setup>
import { ref } from 'vue'

const range = ref(null)

const shortcuts = {
  'Today': () => {
    const now = Date.now()
    return [now, now]
  },
  'Last 7 Days': () => {
    const now = Date.now()
    return [now - 7 * 86400000, now]
  },
  'Last 30 Days': () => {
    const now = Date.now()
    return [now - 30 * 86400000, now]
  }
}
</script>

Disabled Specific Dates

<template>
  <n-space vertical>
    <n-date-picker
      type="date"
      :is-date-disabled="isDateDisabled"
    />
    <n-date-picker
      type="daterange"
      :is-date-disabled="isRangeDateDisabled"
    />
  </n-space>
</template>

<script setup>
const isDateDisabled = (ts) => {
  const date = new Date(ts)
  return date.getDate() <= 15
}

const isRangeDateDisabled = (ts, phase, value) => {
  if (!value) return false
  const [start] = value
  if (phase === 'end' && start) {
    return ts < start + 7 * 86400000
  }
  return false
}
</script>

Default Time for DateTime

<template>
  <n-space vertical>
    <n-date-picker
      type="datetime"
      default-time="13:22:11"
      clearable
    />
    <n-date-picker
      type="datetimerange"
      :default-time="['09:00:00', '18:00:00']"
      clearable
    />
  </n-space>
</template>

Custom Actions

<template>
  <n-space vertical>
    <n-date-picker v-model:value="ts1" type="date" :actions="['now']" />
    <n-date-picker v-model:value="ts2" type="datetime" :actions="['now']" />
    <n-date-picker
      v-model:value="range"
      type="daterange"
      :actions="null"
      update-value-on-close
    />
  </n-space>
</template>

Panel Only Mode

<template>
  <n-date-picker panel type="date" v-model:value="value" />
</template>

Custom Format

<template>
  <n-date-picker
    v-model:value="timestamp"
    type="datetime"
    format="yyyy/MM/dd HH:mm"
    clearable
  />
</template>

Month, Year, Quarter, Week Pickers

<template>
  <n-space vertical>
    <n-date-picker v-model:value="month" type="month" clearable />
    <n-date-picker v-model:value="year" type="year" clearable />
    <n-date-picker v-model:value="quarter" type="quarter" clearable />
    <n-date-picker v-model:value="week" type="week" clearable />
  </n-space>
</template>

Using Methods via Ref

<template>
  <n-space item-style="display: flex; align-item: center;">
    <n-button @click="handleClick">Focus then blur in 1 second</n-button>
    <n-date-picker ref="datePickerRef" style="width: 200px" />
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const datePickerRef = ref(null)

const handleClick = () => {
  datePickerRef.value?.focus()
  setTimeout(() => {
    datePickerRef.value?.blur()
  }, 1000)
}
</script>

Custom Icons

<template>
  <n-date-picker type="date">
    <template #date-icon>
      <n-icon :size="16" :component="RocketOutline" />
    </template>
  </n-date-picker>
</template>

<script setup>
import { RocketOutline } from '@vicons/ionicons5'
</script>

Best Practices

1. Use timestamps for value binding: The component uses millisecond timestamps for consistent date handling.

2. Use formatted-value for string values: When you need string values (e.g., for API), use v-model:formatted-value with value-format.

3. Implement shortcuts for common selections: Provide shortcuts for frequently used date ranges to improve UX.

4. Use is-date-disabled for validation: Disable invalid dates proactively rather than showing errors after selection.

5. Set update-value-on-close for range pickers: This prevents intermediate updates during range selection.

6. Use panel mode for embedded calendars: When embedding in custom UI, use panel mode without the input field.

7. Configure first-day-of-week for locale: Set appropriately for your target audience (0 = Monday, 6 = Sunday).

8. Use default-time for consistent datetime selection: Set default times to ensure consistent datetime values.

9. Leverage fast-year-select and fast-month-select: Enable these for quicker date selection in forms.