Nb Calendar

This is a calendar component for Vue.js 3+.

Loading component...

Installation

Yarn

yarn add @vlalg-nimbus/nb-calendar

Usage

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

import NbCalendarComponents from '@vlalg-nimbus/nb-calendar'
import "@vlalg-nimbus/nb-calendar/dist/style.css";

const app = createApp(App)
app.use(NbCalendarComponents)
app.mount('#app')

To use, simply call the component, in this case it will be NbCalendar or nb-calendar.

Mode 1

<template>
  <NbCalendar />
</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
value	Date/String/Object	null	Defines the initial calendar value. Accepts Date, String ISO, ou Object (para ranges)

Other props

name	Value type	Default	Description
nbId (*)	String		Sets the id attribute to differentiate from other components
display	String	'b'	Defines the display type. Accepts ib and b.
tabIndex	Number	0	Defines the tab index. Set this property to make the calendar focusable by the keyboard.
ariaLabel	String	'Calendar'	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 calendar is disabled
isRequired	Boolean	false	Defines if the calendar is required
width	Number	280	Defines the calendar width in pixels. Minimum value is 280px.
widthFull	Boolean	false	Defines if the calendar should occupy 100% of its parent container width.
fontFamily	String	"'Lato', sans-serif"	Defines the font-family
fontSize	String	'1.6em'	Defines the font-size
fontWeight	Number	400	Defines the font-weight
value	Date/String/Object	null	Defines the initial calendar value. Accepts Date, String (YYYY-MM-DD, YYYY-MM-DDTHH:mm, YYYY-MM-DDTHH:mm:ss, YYYY-MM, YYYY-Www), or Object with `startDate` and `endDate` for range mode.
goToDate	Date/String	null	Navigates the calendar to a specific date. Accepts Date or String (YYYY-MM-DD).
inputType	String	'date'	Defines the input type. Accepts date, month, time, datetime-local, week.
hasSeconds	Boolean	false	Defines if the time picker should include seconds. Only works with `inputType="time"` or `inputType="datetime-local"`.
locale	String	'pt-BR'	Defines the locale. Accepts pt-BR and en-US.
startWeekOnMonday	Boolean	false	Defines if the week should start on Monday instead of Sunday.
allowRange	Boolean	false	Defines if date range selection is allowed.
editRange	Boolean	true	Defines if the range can be edited by dragging the start or end dates. Only works when `allowRange` is `true`.
maxRangeDays	Number	null	Defines the maximum number of days that can be selected in a range. If `null`, there is no limit.
min	Date/String	null	Defines the minimum selectable date. Accepts Date or String (YYYY-MM-DD). For time types, accepts String (HH:mm or HH:mm:ss).
max	Date/String	null	Defines the maximum selectable date. Accepts Date or String (YYYY-MM-DD). For time types, accepts String (HH:mm or HH:mm:ss).
step	String/Number	null	Defines the step for date selection. For `inputType="date"`, step is in days. For `inputType="time"` or `inputType="datetime-local"`, step is in seconds.
minYear	Number	1900	Defines the minimum year available in the year picker.
maxYear	Number	2100	Defines the maximum year available in the year picker.
primaryColor	String	'#007bff'	Defines the primary color. Accepts Hex format (e.g., #007bff).
selectionColor	String	'#1976d2'	Defines the background color for selected dates. Accepts Hex format (e.g., #1976d2).
eventColor	String	'#4caf50'	Defines the color for event indicators. Accepts Hex format (e.g., #4caf50).
todayColor	String	'#007bff'	Defines the color for today's date. Accepts Hex format (e.g., #007bff).
normalTextColor	String	null	Defines the text color for month/year picker items. If `null`, uses theme default. Accepts Hex format.
hoverTextColor	String	null	Defines the text color for month/year picker items on hover. If `null`, uses theme default. Accepts Hex format.
monthYearItemBg	String	null	Defines the background color for month/year picker items. If `null`, uses theme default. Accepts Hex or RGB/RGBA format.
monthYearItemBgHover	String	null	Defines the background color for month/year picker items on hover. If `null`, uses theme default. Accepts Hex or RGB/RGBA format.
dayHoverBg	String	null	Defines the background color for days on hover. If `null`, uses theme default. Accepts Hex or RGB/RGBA format.
dayHoverTextColor	String	null	Defines the text color for days on hover. If `null`, uses theme default. Accepts Hex format.
timeDisplayTextColor	String	null	Defines the text color for the time display section. If `null`, uses theme default. Accepts Hex format.
timeEditButtonBg	String	null	Defines the background color for the time edit button. If `null`, uses theme default. Accepts Hex or RGB/RGBA format.
timeEditButtonTextColor	String	null	Defines the text color for the time edit button. If `null`, uses theme default. Accepts Hex format.
timeEditButtonBgHover	String	null	Defines the background color for the time edit button on hover. If `null`, uses theme default. Accepts Hex or RGB/RGBA format.
timeEditButtonTextColorHover	String	null	Defines the text color for the time edit button on hover. If `null`, uses theme default. Accepts Hex format.
events	Array		Defines an array of events to display on the calendar. Each event should have a `date` property (Date or String) and optionally a `color` property (Hex format).
borderRadius	Number	0	Defines the border radius of the calendar in pixels.
scrollClass	String	''	Defines a custom CSS class for the scrollable content area (useful for custom scrollbar styling). Applied to calendar days, month grid, year grid, weekdays, time picker, and time display sections.

Events

changed

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

For inputType="date":

Returns: Date object or String (format: YYYY-MM-DD)
Example: new Date('2024-01-15') or "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 if hasSeconds is true)
Example: "14:30" or "14:30:45"

For inputType="datetime-local":

Returns: String (format: YYYY-MM-DDTHH:mm or YYYY-MM-DDTHH:mm:ss if hasSeconds is true)
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
Example: { startDate: Date, endDate: Date } or { startDate: null, endDate: null } when cleared

When selection is cleared:

Returns: null

date-selected

Fired when a date is selected, returns detailed information about the selection. The return format varies based on the inputType and selection mode:

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

{
  date: Date,                    // Date object of the selected date
  dateString: String,            // Date in YYYY-MM-DD format (e.g., "2024-01-15")
  isoString: String,             // ISO 8601 string with timezone (e.g., "2024-01-15T00:00:00.000Z")
  isoStringLocal: String,        // ISO 8601 string without timezone (e.g., "2024-01-15T00:00:00")
  day: {                         // Day object with additional information
    date: Number,                // Day of month (1-31)
    fullDate: Date,              // Full date object
    isOtherMonth: Boolean,       // Whether the day belongs to another month
    isToday: Boolean,            // Whether the day is today
    isSelected: Boolean,         // Whether the day is selected
    isInRange: Boolean,          // Whether the day is in a range (if range mode)
    isRangeStart: Boolean,       // Whether the day is the start of a range
    isRangeEnd: Boolean,         // Whether the day is the end of a range
    isDisabled: Boolean,         // Whether the day is disabled
    events: Array                // Array of events for this day
  }
}

When selection is cleared:

{
  date: null,
  dateString: null,
  day: null
}

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

{
  startDate: Date,               // Start date of the range (or null)
  endDate: Date,                 // End date of the range (or null)
  isRange: true,                 // Always true for range mode
  isoString: {                   // ISO strings for both dates (null if incomplete)
    start: String,               // ISO string for start date
    end: String                  // ISO string for end date
  } | null,
  isoStringLocal: {              // Local ISO strings (null if incomplete)
    start: String,               // Local ISO string for start date
    end: String                  // Local ISO string for end date
  } | null
}

When range is cleared:

{
  startDate: null,
  endDate: null,
  isRange: true,
  isoString: null,
  isoStringLocal: null
}

Week Selection (`inputType="week"`)

{
  weekString: String,            // Week in YYYY-Www format (e.g., "2024-W03")
  weekStartDate: Date,           // Date object of Monday (start of week)
  weekEndDate: Date,             // Date object of Sunday (end of week)
  weekNumber: Number,            // Week number (1-53)
  weekYear: Number,              // ISO week year
  isoString: String,             // ISO 8601 string of week start date
  isoStringLocal: String         // Local ISO 8601 string of week start date
}

When selection is cleared:

{
  weekString: null,
  weekStartDate: null,
  weekEndDate: null
}

Month Selection (`inputType="month"`)

{
  date: Date,                    // Date object of the first day of selected month
  dateString: String,            // Month in YYYY-MM format (e.g., "2024-01")
  month: Number,                 // Month index (0-11, where 0 = January)
  year: Number,                  // Year (e.g., 2024)
  monthName: String,             // Full month name (e.g., "Janeiro" or "January")
  isoString: String,             // ISO 8601 string of first day of month
  isoStringLocal: String         // Local ISO 8601 string of first day of month
}

Time Selection (`inputType="time"`)

{
  hour: Number,                  // Selected hour (0-23)
  minute: Number,                // Selected minute (0-59)
  second: Number,                // Selected second (0-59, only if hasSeconds is true)
  timeString: String             // Time in HH:mm or HH:mm:ss format (e.g., "14:30" or "14:30:45")
}

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

{
  date: Date,                    // Date object of the selected date
  hour: Number,                  // Selected hour (0-23)
  minute: Number,                // Selected minute (0-59)
  second: Number,                // Selected second (0-59, only if hasSeconds is true)
  datetimeString: String,       // Combined date and time in YYYY-MM-DDTHH:mm format (e.g., "2024-01-15T14:30")
  isoString: String,             // ISO 8601 string with timezone
  isoStringLocal: String,        // Local ISO 8601 string without timezone
  day: {                         // Day object (same structure as single date selection)
    date: Number,
    fullDate: Date,
    isOtherMonth: Boolean,
    isToday: Boolean,
    isSelected: Boolean,
    isInRange: Boolean,
    isRangeStart: Boolean,
    isRangeEnd: Boolean,
    isDisabled: Boolean,
    events: Array
  }
}

month-changed

Fired when the month/year changes through navigation (using previous/next buttons or month/year pickers), returns:

{
  year: Number,                  // Current year (e.g., 2024)
  month: Number,                 // Current month index (0-11, where 0 = January)
  monthName: String              // Full month name in current locale (e.g., "Janeiro" or "January")
}

Example:

{
  year: 2024,
  month: 0,                      // January
  monthName: "Janeiro"           // or "January" if locale is "en-US"
}

Slots

The component does not have custom slots. All customization is done through props.

Examples

Basic Date Selection

<template>
  <NbCalendar
    nb-id="calendar-basic"
    @changed="onDateChanged"
  />
</template>

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

Date Range Selection

<template>
  <NbCalendar
    nb-id="calendar-range"
    :allow-range="true"
    :edit-range="true"
    :max-range-days="30"
    @date-selected="onRangeChanged"
  />
</template>

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

Week Selection

<template>
  <NbCalendar
    nb-id="calendar-week"
    input-type="week"
    @changed="onWeekChanged"
  />
</template>

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

Month Selection

<template>
  <NbCalendar
    nb-id="calendar-month"
    input-type="month"
    @changed="onMonthChanged"
  />
</template>

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

Time Selection

<template>
  <NbCalendar
    nb-id="calendar-time"
    input-type="time"
    :has-seconds="true"
    @date-selected="onTimeChanged"
  />
</template>

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

DateTime Selection

<template>
  <NbCalendar
    nb-id="calendar-datetime"
    input-type="datetime-local"
    :has-seconds="true"
    @date-selected="onDateTimeChanged"
  />
</template>

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

Calendar with Events

<template>
  <NbCalendar
    nb-id="calendar-events"
    :events="events"
    @date-selected="onDateChanged"
  />
</template>

<script setup>
const events = [
  { date: new Date('2024-01-15'), color: '#4caf50' },
  { date: new Date('2024-01-20'), color: '#ff9800' },
  { date: '2024-01-25', color: '#f44336' }
]

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

Dark Theme Calendar

<template>
  <NbCalendar
    nb-id="calendar-dark"
    theme="dark"
    :width="400"
    @changed="onDateChanged"
  />
</template>

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

Calendar with Custom Colors

<template>
  <NbCalendar
    nb-id="calendar-custom"
    primary-color="#9c27b0"
    selection-color="#7b1fa2"
    event-color="#e91e63"
    today-color="#673ab7"
    @changed="onDateChanged"
  />
</template>

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

Calendar with Min/Max Dates

<template>
  <NbCalendar
    nb-id="calendar-limited"
    min="2024-01-01"
    max="2024-12-31"
    :step="7"
    @changed="onDateChanged"
  />
</template>

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

Full Width Calendar

<template>
  <div style="width: 100%; padding: 20px;">
    <NbCalendar
      nb-id="calendar-full"
      :width-full="true"
      @changed="onDateChanged"
    />
  </div>
</template>

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

Calendar with Custom Scrollbar

<template>
  <NbCalendar
    nb-id="calendar-scroll"
    scroll-class="custom-scrollbar"
    @changed="onDateChanged"
  />
</template>

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

<style scoped>
:deep(.calendar) {
  .custom-scrollbar {
    &::-webkit-scrollbar {
      width: 8px;
    }

    &::-webkit-scrollbar-track {
      background: tomato;
    }

    &::-webkit-scrollbar-thumb {
      background: #640dfb;
      border-radius: 4px;

      &:hover {
        background: #4d0bc0;
      }
    }
  }
}
</style>

Nb Imagesnb-image

Nb PaginationNb Pagination