nb-date-picker

This is a date picker component for Vue.js 3+.

Loading component...

Installation

Yarn

yarn add @vlalg-nimbus/nb-inputs

Usage

import { createApp } from 'vue'
import App from './App.vue'

import NbInputComponents from '@vlalg-nimbus/nb-inputs'
import "@vlalg-nimbus/nb-inputs/dist/style.css";

// Import the Calendar component from the npm package to use in the nb-date-picker component
import { Calendar } from '@vlalg-nimbus/nb-calendar';
import "@vlalg-nimbus/nb-calendar/dist/style.css"

const app = createApp(App)
app.use(NbInputComponents)
app.component('Calendar', Calendar); // Register the Calendar component globally
app.mount('#app')

To use, simply call the component, in this case it will be NbDatePicker or nb-date-picker.

Mode 1

<template>
  <NbDatePicker />
</template>

Preview & Playground

Select the component you want to edit/test

Loading Sandbox...

Props

Items with an (*) mean they are required

To set initial value, use the inputText prop.

name	Value type	Default	Description
inputText	String	''	Defines the initial date value. Accepts String in ISO format (YYYY-MM-DD, YYYY-MM-DDTHH:mm, YYYY-MM-DDTHH:mm:ss, YYYY-MM, YYYY-Www) or JSON string for ranges.

Other props

name	Value type	Default	Description
nbId (*)	String		Sets the id attribute to differentiate from other components
inputName (*)	String		Sets the name attribute for the input element
display	String	'b'	Defines the display type. Accepts ib and b.
tabIndex	Number	0	Defines the tab index. Set this property to make the input focusable by the keyboard.
hasTabIndexEnter	Boolean	true	Defines if pressing Enter should trigger the entered event.
ariaLabel	String	'Alternate Text Button'	Defines the aria-label attribute for screen readers.
ariaAttrs	Object	{}	Allows passing custom aria attributes as an object. Keys will automatically receive the `aria-` prefix. Example: `{ 'describedby': 'help-id', 'invalid': 'false' }`
theme	String	'light'	Defines the theme. Accepts light and dark.
disabled	Boolean	false	Defines if the input is disabled
required	Boolean	false	Defines if the input is required
inputReadonly	Boolean	false	Defines if the input is readonly
inputType	String	'date'	Defines the input type. Accepts date, month, time, datetime-local, week.
inputText	String	''	Defines the initial input value. Accepts String in ISO format (YYYY-MM-DD, YYYY-MM-DDTHH:mm, YYYY-MM-DDTHH:mm:ss, YYYY-MM, YYYY-Www) or JSON string for ranges.
locale	String	'pt-BR'	Defines the locale. Accepts pt-BR and en-US.
allowRange	Boolean	false	Defines if date range selection is allowed. When enabled, the input accepts ranges in format "DD/MM/YYYY - DD/MM/YYYY".
useCustomCalendar	Boolean	true	Defines if the component should use the custom calendar component. If `false`, uses the native browser date picker.
calendarZIndex	Number	10000	Defines the z-index of the calendar popup when using custom calendar. Useful when the calendar needs to appear above modals or other elements.
calendarWidth	Number	350	Defines the width of the calendar popup in pixels. Minimum value is 280.
min	String	''	Defines the minimum selectable date. Accepts String (YYYY-MM-DD). For time types, accepts String (HH:mm or HH:mm:ss).
max	String	''	Defines the maximum selectable date. Accepts String (YYYY-MM-DD). For time types, accepts String (HH:mm or HH:mm:ss).
step	String/Number	''	Defines the step for date selection. For `inputType="date"`, step is in days. For `inputType="time"` or `inputType="datetime-local"`, step is in seconds.
hasTrim	Boolean	false	Defines if the input value should be trimmed (spaces removed from start and end).
fontFamily	String	"'Lato', sans-serif"	Defines the font-family for the input
fontSize	String	null (default: `1.4em`)	Defines the font-size for the input. If `null`, uses `1.4em` as default size. Pass a string with the font-size and the unit (e.g., "1.2em").
fontWeight	Number	400	Defines the font-weight for the input
textColor	String	'#ffffff'	Defines the text color for the input
caretColor	String	''	Defines the caret (cursor) color. If empty, uses theme default.
selectionBgColor	String	''	Defines the background color for selected text. If empty, uses theme default.
selectionTextColor	String	''	Defines the text color for selected text. If empty, uses theme default.
hasBorderRadius	Boolean	false	Defines if the input should have border radius
borderRadius	Number	0.5	Defines the border radius in rem units. Only applies if `hasBorderRadius` is `true` and `inputStyle` is not `'line'`.
inputWidth	Number	200	Defines the input width in pixels. Only applies when `display` is not `'b'`.
inputStyle	String	'background'	Defines the input style. Accepts background, line, and border.
activeTextStyle	String	'normal'	Defines the text style when input is active. Accepts normal, italic, and oblique.
inputUppercase	Boolean	false	Defines if the input text should be displayed in uppercase
inputAutocomplete	String	'on'	Defines the autocomplete attribute. Accepts on and off.
textAlign	String	'left'	Defines the text alignment. Accepts left, center, and right.
showLabel	Boolean	false	Defines if the label should be displayed
label	String	'Label text'	Defines the label text
labelBackground	String	'transparent'	Defines the background color for the label when active (floating)
labelPadding	String	'1px 5px'	Defines the padding for the label when active (floating)
labelBorderRadius	Number	0	Defines the border radius for the label when active (floating)
labelLeft	Number	5	Defines the left position of the label when inactive (inside input)
inputLabelMarginActive	Number	15	Defines the top margin of the input when label is active (floating)
labelActiveTop	Number	-13	Defines the top position of the label when active (floating)
labelActiveLeft	Number	5	Defines the left position of the label when active (floating)
fontFamilyLabel	String	"'Lato', sans-serif"	Defines the font-family for the label
fontSizeLabel	String	'1em'	Defines the font-size for the label when inactive
fontSizeLabelActive	String	'0.8em'	Defines the font-size for the label when active (floating)
fontWeightLabel	Number	400	Defines the font-weight for the label
lightTextColorLabel	String	'#333333'	Defines the text color for the label in light theme
lightTextColorLabelActive	String	'#333333'	Defines the text color for the label when active in light theme
darkTextColorLabel	String	'#ffffff'	Defines the text color for the label in dark theme
darkTextColorLabelActive	String	'#ffffff'	Defines the text color for the label when active in dark theme
lightBgColor	String	'#f8f8f2'	Defines the background color for the input in light theme
lightBgColorFocus	String	'#eaeaea'	Defines the background color for the input when focused in light theme
lightDisabledBgColor	String	'#dfdfd9'	Defines the background color for the input when disabled in light theme
lightTextColor	String	'#000000'	Defines the text color for the input in light theme
darkBgColor	String	'#353734'	Defines the background color for the input in dark theme
darkBgColorFocus	String	'#272936'	Defines the background color for the input when focused in dark theme
darkDisabledBgColor	String	'rgba(40, 42, 54, 1)'	Defines the background color for the input when disabled in dark theme
darkTextColor	String	'#000000'	Defines the text color for the input in dark theme
fontFamilyMsg	String	"'Lato', sans-serif"	Defines the font-family for the message
fontSizeMsg	String	'1em'	Defines the font-size for the message
fontWeightMsg	Number	400	Defines the font-weight for the message
textMessageColor	String	'#f15574'	Defines the text color for the message
showMsg	Boolean	false	Defines if the message should be displayed
hasMsg	Boolean	false	Defines if there is a message to display
message	String	'Default message text'	Defines the message text
hasCustomMsg	Boolean	false	Defines if the message uses custom styling
sizeMediaQuery	String	'sm'	Defines the size media query. Accepts xs, sm, md, and lg. Currently always uses 'sm'.
tabindex	String/Number	0	Defines the tabindex attribute for the input

Events

changed

Fired when the input value changes, returns the current value in different formats depending on the inputType:

For inputType="date":

Returns: String (format: YYYY-MM-DD)
Example: "2024-01-15"

For inputType="month":

Returns: String (format: YYYY-MM)
Example: "2024-01"

For inputType="time":

Returns: String (format: HH:mm or HH:mm:ss)
Example: "14:30" or "14:30:45"

For inputType="datetime-local":

Returns: String (format: YYYY-MM-DDTHH:mm or YYYY-MM-DDTHH:mm:ss)
Example: "2024-01-15T14:30" or "2024-01-15T14:30:45"

For inputType="week":

Returns: String (format: YYYY-Www - ISO 8601 week format)
Example: "2024-W03"

For range mode (allowRange="true"):

Returns: Object with startDate and endDate properties (Date objects)
Example: { startDate: Date, endDate: Date } or { startDate: null, endDate: null } when cleared

When input is cleared:

Returns: '' (empty string) for single date or { startDate: null, endDate: null } for range mode

Detailed Return Formats

The changed event returns values in different formats based on the inputType. Here are the detailed return formats:

Single Date Selection (`inputType="date"`)

Returns: String in format YYYY-MM-DD

Example:

"2024-01-15"

When selection is cleared:

""

Date Range Selection (`allowRange="true"`)

Returns: Object with startDate and endDate properties

{
  startDate: Date,               // Start date of the range (or null)
  endDate: Date                  // End date of the range (or null)
}

Example:

{
  startDate: new Date('2024-01-15'),
  endDate: new Date('2024-01-20')
}

When range is cleared:

{
  startDate: null,
  endDate: null
}

When only start date is selected (partial range):

{
  startDate: new Date('2024-01-15'),
  endDate: null
}

Week Selection (`inputType="week"`)

Returns: String in ISO 8601 week format YYYY-Www

Example:

"2024-W03"  // Week 3 of year 2024

When selection is cleared:

""

Month Selection (`inputType="month"`)

Returns: String in format YYYY-MM

Example:

"2024-01"  // January 2024

When selection is cleared:

""

Time Selection (`inputType="time"`)

Returns: String in format HH:mm or HH:mm:ss

Example:

"14:30"        // 2:30 PM
"14:30:45"     // 2:30:45 PM (if seconds are included)

When selection is cleared:

""

DateTime Selection (`inputType="datetime-local"`)

Returns: String in format YYYY-MM-DDTHH:mm or YYYY-MM-DDTHH:mm:ss

Example:

"2024-01-15T14:30"        // January 15, 2024 at 2:30 PM
"2024-01-15T14:30:45"     // January 15, 2024 at 2:30:45 PM (if seconds are included)

When selection is cleared:

""

current-value

Fired whenever the input value changes (same as changed but with a different name for compatibility). Returns the same format as changed.

focused

Fired when the input receives focus.

Returns: No return value

Example:

@focused="onInputFocused"

const onInputFocused = () => {
  console.log('Input focused')
}

blurred

Fired when the input loses focus.

Returns: No return value

Example:

@blurred="onInputBlurred"

const onInputBlurred = () => {
  console.log('Input blurred')
}

clicked

Fired when the input or its container is clicked.

Returns: No return value

Example:

@clicked="onInputClicked"

const onInputClicked = () => {
  console.log('Input clicked')
}

entered

Fired when the user presses Enter while the input is focused. Only fires if hasTabIndexEnter is true and the input is not disabled or readonly.

Returns: The current input value (same format as changed)

Example:

@entered="onEnterPressed"

const onEnterPressed = (value) => {
  console.log('Enter pressed with value:', value)
}

Slots

message

Custom slot for the message area. Allows custom HTML/content to be displayed as the message.

Example:

<nb-date-picker nb-id="datepicker-1" input-name="date">
  <template #message>
    <span>Custom error message</span>
  </template>
</nb-date-picker>

Examples

Basic Date Selection

<template>
  <NbDatePicker
    nb-id="datepicker-basic"
    input-name="date"
    @changed="onDateChanged"
  />
</template>

<script setup>
const onDateChanged = (value) => {
  console.log('Selected date:', value)
}
</script>

Date Range Selection

<template>
  <NbDatePicker
    nb-id="datepicker-range"
    input-name="date-range"
    :allow-range="true"
    :use-custom-calendar="true"
    @changed="onRangeChanged"
  />
</template>

<script setup>
const onRangeChanged = (value) => {
  console.log('Selected range:', value)
  // value will be: { startDate: Date, endDate: Date }
}
</script>

Week Selection

<template>
  <NbDatePicker
    nb-id="datepicker-week"
    input-name="week"
    input-type="week"
    @changed="onWeekChanged"
  />
</template>

<script setup>
const onWeekChanged = (value) => {
  console.log('Selected week:', value) // Format: YYYY-Www
}
</script>

Month Selection

<template>
  <NbDatePicker
    nb-id="datepicker-month"
    input-name="month"
    input-type="month"
    @changed="onMonthChanged"
  />
</template>

<script setup>
const onMonthChanged = (value) => {
  console.log('Selected month:', value) // Format: YYYY-MM
}
</script>

Time Selection

<template>
  <NbDatePicker
    nb-id="datepicker-time"
    input-name="time"
    input-type="time"
    @changed="onTimeChanged"
  />
</template>

<script setup>
const onTimeChanged = (value) => {
  console.log('Selected time:', value) // Format: HH:mm or HH:mm:ss
}
</script>

DateTime Selection

<template>
  <NbDatePicker
    nb-id="datepicker-datetime"
    input-name="datetime"
    input-type="datetime-local"
    @changed="onDateTimeChanged"
  />
</template>

<script setup>
const onDateTimeChanged = (value) => {
  console.log('Selected datetime:', value) // Format: YYYY-MM-DDTHH:mm
}
</script>

DatePicker with Label

<template>
  <NbDatePicker
    nb-id="datepicker-label"
    input-name="date"
    :show-label="true"
    label="Select a date"
    @changed="onDateChanged"
  />
</template>

<script setup>
const onDateChanged = (value) => {
  console.log('Selected date:', value)
}
</script>

Dark Theme DatePicker

<template>
  <NbDatePicker
    nb-id="datepicker-dark"
    input-name="date"
    theme="dark"
    :input-width="300"
    @changed="onDateChanged"
  />
</template>

<script setup>
const onDateChanged = (value) => {
  console.log('Selected date:', value)
}
</script>

DatePicker with Min/Max Dates

<template>
  <NbDatePicker
    nb-id="datepicker-limited"
    input-name="date"
    min="2024-01-01"
    max="2024-12-31"
    :step="7"
    @changed="onDateChanged"
  />
</template>

<script setup>
const onDateChanged = (value) => {
  console.log('Selected date:', value)
}
</script>

DatePicker with Custom Calendar Disabled

<template>
  <NbDatePicker
    nb-id="datepicker-native"
    input-name="date"
    :use-custom-calendar="false"
    @changed="onDateChanged"
  />
</template>

<script setup>
const onDateChanged = (value) => {
  console.log('Selected date:', value)
}
</script>

DatePicker with Custom Styling

<template>
  <NbDatePicker
    nb-id="datepicker-custom"
    input-name="date"
    :has-border-radius="true"
    :border-radius="0.8"
    input-style="border"
    :input-width="250"
    text-align="center"
    @changed="onDateChanged"
  />
</template>

<script setup>
const onDateChanged = (value) => {
  console.log('Selected date:', value)
}
</script>

DatePicker with Message

<template>
  <NbDatePicker
    nb-id="datepicker-message"
    input-name="date"
    :show-msg="true"
    :has-msg="true"
    message="Please select a valid date"
    @changed="onDateChanged"
  />
</template>

<script setup>
const onDateChanged = (value) => {
  console.log('Selected date:', value)
}
</script>

DatePicker with Custom Locale

<template>
  <NbDatePicker
    nb-id="datepicker-locale"
    input-name="date"
    locale="en-US"
    @changed="onDateChanged"
  />
</template>

<script setup>
const onDateChanged = (value) => {
  console.log('Selected date:', value)
}
</script>

Nb Inputsnb-textarea

Nb Loadersnb-loaders