n-date-picker

A comprehensive date picker component supporting various date types (date, datetime, range, month, year, quarter, week) with formatting, validation, shortcuts, and async operations

SKILL.md

GitHub

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

Name Type Default Description
value / v-model:value number | [number, number] | null undefined Value as timestamp (ms).
clearable boolean false Whether the picker is clearable.
default-value number | [number, number] | null undefined Default value.
disabled boolean false Whether the picker is disabled.
first-day-of-week 0 | 1 | 2 | 3 | 4 | 5 | 6 undefined First day of week (0 = Monday).
input-readonly boolean false Set readonly on input.
panel boolean false Use as panel only (no input).
placement 'top-start' | 'top' | ... 'bottom-start' Panel placement.
placeholder string Type-specific Placeholder text.
shortcuts Record<string, number | (() => number)> undefined Shortcut buttons.
show boolean undefined Whether to show panel.
size 'small' | 'medium' | 'large' 'medium' Picker size.
status 'success' | 'warning' | 'error' undefined Validation status.
to string | HTMLElement | false body Panel container.
type 'date' | 'datetime' | 'daterange' | ... 'date' Picker type.
value-format string Follows format Format of binding value.
format string Type-specific Display format.

Date Type Props

Name Type Default Description
actions Array<'clear' | 'now'> | null ['clear', 'now'] Panel actions.
is-date-disabled (current, detail) => boolean () => false Date validator.
fast-year-select boolean false Close panel after year select.
fast-month-select boolean false Close panel after month select.

DateTime Type Props

Name Type Default Description
actions Array<'clear' | 'now' | 'confirm'> | null ['clear', 'now', 'confirm'] Panel actions.
default-time string | (timestamp) => string undefined Default time for selected date.
is-time-disabled (current) => {...} undefined Time validator.
time-picker-props TimePickerProps undefined Time picker props.
update-value-on-close boolean false Update value on panel close.

DateRange Type Props

Name Type Default Description
actions Array<'clear' | 'confirm'> | null ['clear', 'confirm'] Panel actions.
bind-calendar-months boolean false Consecutive calendar months.
start-placeholder string 'Start Date' Start placeholder.
end-placeholder string 'End Date' End placeholder.
separator string internal icon Range separator.
close-on-select boolean false Close after selection.
update-value-on-close boolean false Update on close.

Events

Name Parameters Description
update:value (value, formattedValue) Triggered when value changes.
update:formatted-value (value, timestampValue) Triggered for formatted value.
update:show (show: boolean) Triggered when panel shows/hides.
blur () Triggered on blur.
focus () Triggered on focus.
clear () Triggered on clear.
confirm (value, formattedValue) Triggered on confirm.
prev-month () Triggered on previous month click.
next-month () Triggered on next month click.
prev-year () Triggered on previous year click.
next-year () Triggered on next year click.

Slots

Name Parameters Description
date-icon () Date icon in input.
footer () Extra footer content.
separator () Separator for range picker.
prev-month () Previous month icon.
next-month () Next month icon.
prev-year () Previous year icon.
next-year () Next year icon.
clear { onClear, text } Clear button.
confirm { onConfirm, disabled, text } Confirm button.
now { onNow, text } Now button.

Methods

Name Type Description
focus () => void Focus the picker.
blur () => void Blur the picker.

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.