# V-Calendar

V-Calendar is a modern and flexible plugin for displaying simple, attributed calendars in Vue.js. It uses attributes to decorate the calendar with various visual indicators including highlighted date regions, dots, bars, content classes and even popovers for simple tooltips or custom slot content.

Any of these indicators can be displayed for single dates, date ranges and even complex date patterns like the following:

• Every other Friday
• 15th of every month
• Last Friday of every other month.

A date picker is included out of the box with single date, multiple date and date range selection modes. Also, because v-date-picker is simply a wrapper for v-calendar, it supports the same props, slots and custom custom theme support,

And of course, V-Calendar is responsive and mobile friendly.

# Component

v-calendar is the core component. By default, it has a neutral design that should blend nicely within any web application, with various layout configuration options:

• Responsive multi-row and multi-column layouts
• Slot support for custom header and day content
• Semantic-inspired navigation popover
• Navigation transitions (horizontal slide, vertical slide, fade)

<v-calendar />

# Colors & Dark Mode

You can apply a theme color or dark mode by using the color and is-dark props.

<v-date-picker
  mode="range"
  :value="null"
  color="red"
  is-dark
  is-inline
  />

# Layouts

# Full Width

To expand the component to the full width of its container, set the is-expanded prop.

<v-calendar is-expanded />

# Title Positioning

To make the title header left or right aligned, use the title-position prop.

# Left Aligned

<v-calendar title-position="left" />

# Right Aligned

<v-calendar title-position="right" />

# Multiple Rows & Columns

Use the rows and columns props to create multi-row and multi-column static layouts.

<v-calendar :rows="2" />

# Responsive Layouts

V-Calendar allows you build responsive designs for multiple screen sizes.

The basic approach can be described in two steps:

1. Specify a few screen sizes to monitor by providing a set of breakpoints (sm, md, lg and xl). The screen size names and dimensions are configurable.

2. Call the $screens function to assign props or create computed properties based on the current screen size. This function automatically re-evaluates behind the scenes any time the window crosses a breakpoint border.

V-Calendar takes a mobile-first approach, where each screen represents a minimum viewport width. Any values you assign at smaller screen sizes are also applied to larger sizes, unless explicity overridden.

For example, suppose we wish to display a single column on mobile. Then, at the large size, we wish to expand the calendar to two columns.

<v-calendar :columns="$screens({ default: 1, lg: 2 })" />

When calling the $screens function to target multiple screens, pass an object to specify the screen-to-value relationships with target screen sizes as the key. Use the default key to target the default mobile layout.

Alternatively, we can pass the default value as a second parameter to the $screens function.

<!--Same as before, just passing default value as second parameter-->
<v-calendar :columns="$screens({ lg: 2 }, 1)" />

Let's add to the previous example so that a new row is added for large screens. Also, we would also like to expand the pane width to fill its container on mobile when only one column and row is displayed.

<v-calendar
  :columns="$screens({ default: 1, lg: 2 })"
  :rows="$screens({ default: 1, lg: 2 })"
  :is-expanded="$screens({ default: true, lg: false })"
  />

We could rework the previous example to make it a bit more intuitive by creating a comprehensive layout computed property that just calls the $screens function once.

<v-calendar
  :columns="layout.columns"
  :rows="layout.rows"
  :is-expanded="layout.isExpanded"
  />

export default {
  computed: {
    layout() {
      return this.$screens(
        {
          // Default layout for mobile
          default: {
            columns: 1,
            rows: 1,
            isExpanded: true,
          },
          // Override for large screens
          lg: {
            columns: 2,
            rows: 2,
            isExpanded: false,
          },
        },
      );
    }
  }
}

# Screen Sizes

There are 4 screen sizes provided by default:

{
  "sm": "640px",  // (min-width: 640px)
  "md": "768px",  // (min-width: 768px)
  "lg": "1024px", // (min-width: 1024px)
  "xl": "1280px"  // (min-width: 1280px)
}

You may use any number of custom named screens. Just pass the your own custom screens object as part of the defaults when using VCalendar.

import VCalendar from 'v-calendar';

Vue.use(VCalendar, {
  // ...some defaults
  screens: {
    tablet: '576px',
    laptop: '992px',
    desktop: '1200px',
  },
  // ...other defaults
})

Then, reference your custom screens when calling the $screens function.

<v-calendar
  :columns="$screens({ default: 1, laptop: 2 })"
  />

# Working With Dates

Understanding how to configure date expressions is a critical part to using VCalendar. Specifically, they are used for the following purposes:

• Determining where and how attributes are displayed
• Disabling date selection by the user
• Setting the selected date(s) for v-date-picker

In this guide, a date expression may be used to denote any of the following:

• Single Dates
• Date Ranges
• Date Patterns
• Collection of any of the above

# Single Dates

The first type of date expression is a simple native Javascript date object.

Here is an example of using a date to display a simple attribute. We'll get into how to configure attributes in more detail later, but for now we can just focus on the dates expression below:

...
data() {
  return {
    attributes: [
      {
        key: 'today',
        highlight: true,
        dates: new Date()
      }
    ]
  }
}

# Date Ranges

Date ranges define a range of contiguous dates. They are expressed as a simple object with the following properties:

  ...
  dates: [
    { start: new Date(2018, 0, 1), end: new Date(2018, 0, 5) },
    { start: new Date(2018, 0, 15), span: 5 } // # of days
  ]
  ...

A null value denotes an infinite start or end date.

  ...
  dates: {
    start: null, // From the beginning of time
    end: new Date() // Until today
  }
  ...

Optionally, if using null dates, you can omit them entirely.

...
dates: {
  end: new Date() // Same as before
}
...

Thus, an empty object is a valid date expression...

  ...
  // From the beginning of time until the end of time
  dates: {},
  ...

# Date Patterns

Date patterns are an extension of date ranges. They can target dates that would be incredibly difficult, if not impossible, to do otherwise with simple dates or date ranges. To configure a date pattern, let's first start with a simple date range.

  ...
  dates: {
    start: new Date(2018, 0, 1),  // Jan 1st, 2018
    end: new Date(2019, 0, 1)     // Jan 1st, 2019
  },
  ...

The only thing we need to do to convert this date range into a date pattern is to start adding patterns to it. For this example, we'll just target the weekends.

  ...
  dates: {
    start: new Date(2018, 0, 1),  // Jan 1st, 2018
    end: new Date(2019, 0, 1),    // Jan 1st, 2019
    weekdays: [1, 7]              // ...on Sundays and Saturdays
  },
  ...

We can also target other specific day properties, like days: [6, 15] for the 6th and 15th of the month, weeks: [-1] for the last week of the month and even ordinalWeekdays: { [-1]: 1 } for the last Sunday of the month.

For the next example, let's display dot indicators on the last Friday of every other month, starting on January 1st of 2018.

...
  attrs: [
    {
      dot: 'red',
      dates: {
        start: new Date('1/1/2018'),
        monthlyInterval: 2,           // Every other month
        ordinalWeekdays: { [-1]: 6 }  // ...on the last Friday
      }
    }
  ]
...

Pretty cool!! 👌

Now, for some reason, we also want to target the 15th of every other month (in addition to the last Friday), so this might be our first attempt:

...
dates: {
  start: new Date('1/1/2018'),
  monthlyInterval: 2,           // Every other month
  ordinalWeekdays: { [-1]: 6 }, // ...on the last Friday
  days: 15                      // ...and on the 15th? (WRONG!)
},
...

But this would be wrong, because all component specifiers are conditionally anded with each other. In other words, this would only target the last Friday of every other month that also happened to be on the 15th of the month (which would never occur).

To evaluate a set of conditions or another set, we can break the sets of conditions out into an array assigned to the on property.

...
dates: {
  start: new Date('1/1/2018'),
  monthlyInterval: 2,                 // Every other month
  on: [                               // ...on...
    { ordinalWeekdays: { [-1]: 6 } }, // ...the last Friday
    { days: 15 }                      // ...or the 15th of the month
  ]
}
...

Note how we kept the monthlyInterval condition outside of the array. Any conditions that should be anded with all the others can be extracted out of the array. This prevents unnecessary duplication of conditions within the array.

Here is a complete reference of date component specifiers available.

# Collections

Any of the previously mentioned singular date expressions may be combined using an array.

  ...
  dates: [
    new Date(2018, 0, 1),
    {
      start: new Date(2018, 0, 10),
      end: new Date(2018, 0, 12)
    },
    new Date(2018, 0, 15),
  ],
  ...

# Disabling Dates

As mentioned earlier, date expressions are not only used to define attributes. They can also be used to "disable" calendar days. When a date is disabled, the following default behavior is applied:

• Pointer events are disabled for the disabled calendar day cells
• Day text color has less contrast than normal day cells

The classes that define this behavior are defined for via the active theme, specifically the dayContentDisabled and dayDisabled theme settings.

You can disable dates, date ranges and date patterns using the following methods:

# 1. Explicitly via min-date

<v-date-picker
  v-model='date'
  :min-date='new Date()'
  is-inline
  />

# 2. Explicitly via max-date

<v-date-picker
  v-model='date'
  :max-date='new Date()'
  is-inline
  />

# 3. Explicitly via disabled-dates

When using disabled-dates, you can use a full date expression to specify a set of disabled dates. That is, a date object, date range object, date pattern or an array of either of these may be used.

<!--Disable weekend selection-->
<v-date-picker
  mode='range'
  v-model='date'
  :disabled-dates='{ weekdays: [1, 7] }'
  is-inline
  />

# 4. Implicitly via available-dates.

Any dates not included in available-dates are disabled.

<v-date-picker
  :available-dates='{ start: new Date(), end: null }'
  v-model='date'
  is-inline
  />

# Include vs Exclude Dates

Currently, there are four places where date expressions are used:

• attribute.dates: Date(s) to display attributes .
• attribute.excludeDates: Date(s) to NOT display attributes. All other dates are displayed.
• disabled-dates Date(s) to disable for v-calendar & v-date-picker.
• available-dates Date(s) to enable for v-calendar & v-date-picker. All other dates are disabled.

In all places where date expressions are used, you'll notice that they come in pairs. One expression is for the explicit form (dates, disabled-dates), and the other expression is for the implicit form (exclude-dates, available-dates).

The explicit form is the most direct form of expressing what dates to target.

However, it might be more efficient to express what dates you would like to exclude, or avoid. For example, in v-date-picker, if you only want to allow date selections in the month of January of 2018, both of these expressions would work just fine:

<v-date-picker
  v-model='myDate'
  :disabled-dates='[
    {
      start: null,
      end: new Date(2017, 11, 31)
    },
    {
      start: new Date(2018, 1, 1),
      end: null
    }
  ]'
  />

<v-date-picker
  v-model='myDate'
  :available-dates='{
    start: new Date(2018, 0, 1),
    end: new Date(2018, 0, 31)
  }'
  />

The second expression is more terse and declarative than the first. It even performs slighly better. The point is, just take a second to consider which method is best suited for your application.

# i18n

VCalendar utilizes the well supported Internationalization API to derive month and weekday names and formatting. This helps keep the package size down, as well as supporting multiple locales in the most performant and isomorphic way.

# Locales

A locale includes multiple settings that are typically assigned on a per region basis. This currently includes the following:

There are multiple ways which you can configure the locale for a specific calendar. Locales may be configured globally via the defaults object as well as on a per-calendar basis with the locale prop.

# No specified locale

<v-calendar />

With no locale specified, the locale detected by the Internationalization API is used.

# No specified locale w/ override props

<v-calendar :first-day-of-week="2" :masks="{ title: 'MMM YYYY' }" />

Uses the detected locale with customized firstDayOfWeek or masks that will override the built-in locale settings. When using a customized masks prop, the default masks will supply any masks that are missing, so you are free to provide single overrides.

# String Locale

<v-calendar locale="es" />

With a string locale, the locale with the matching identifier is used. The Internationalization API is used to generate the dayNames, dayNamesShort, dayNamesShorter, dayNamesNarrow, monthNames and monthNamesShort properties. Because the API does not provide common values for the firstDayOfWeek or masks these are loaded from the plugin defaults (unless specifically provided via props).

# Object Locale

<v-calendar :locale="{ id: 'da', firstDayOfWeek: 2, masks: { weekdays: 'WW' } }" />

With an object locale, you can simply provide all the settings you need together in a single object. Note that firstDayOfWeek and masks props will override this object.

# Providing default locales for all calendars

More conveniently, you may override or provide missing locale information via the locales property of the defaults object when using VCalendar. This should be an object with the locale identifier as the key and an object with the locale settings.

import Vue from 'vue'
import VCalendar from 'v-calendar'

Vue.use(VCalendar, {
  locales: {
    'pt-PT': {
      firstDayOfWeek: 1,
      masks: {
        L: 'YYYY-MM-DD',
        // ...optional `title`, `weekdays`, `navMonths`, etc
      }
    }
  }
});

Then, all you need to do is reference your locale when using the calendar component.

<v-calendar locale="pt-PT" />

# Formatting & Parsing Dates

As mentioned before, the locale masks are used to properly format and/or parse dates for the following calendar sections:

# Parsing using multiple masks

You'll notice an array was used to specify the input mask for v-date-picker. This is because it uses the supplied masks(s) to parse, as well as display, the selected date. The first supplied mask is used to display the date selection, while all masks are used (from first to last) to parse the date string. The first successfully parsed date is used as the selected date. This provides more flexibility for the user when manually typing in dates.

By default, v-date-picker will first try and use the localized long date mask to parse the date, but will also try to parse masks that are globally unambiguous (YYYY-MM-DD and YYYY/MM/DD). Furthermore, because v-date-picker uses its own parsing logic (rather than relying on the browser's inconsistent Date.parse function), it can properly parse ISO-8601 dates to the user's local time zone instead of converting to UTC. If you plan on targeting browsers from multiple locales, it is probably best to defer to the default mask settings.

# Mask Tokens

Use the following tokens to configure your custom masks:

With all of this in mind, it is probably best that you rely on the the plugin's built-in methods for detecting the user's locale. However, if you would like to force a specific locale for all users, you may supply your own default locale using the language-region format.

# Installation

Vue.js version 2.5+ is required.

# NPM

# 1 Install via npm

npm install v-calendar@next

# 2 Import and use VCalendar

# 2A. Plugin Method (Recommended)

This is the most common use case.

import Vue from 'vue';
import VCalendar from 'v-calendar';

// Use v-calendar & v-date-picker components
Vue.use(VCalendar, {
  componentPrefix: 'vc',  // Use <vc-calendar /> instead of <v-calendar />
  ...,                // ...other defaults
});

# 2B. Components Method

Or, you can just import and use the calendar if you don't need the v-date-picker or v-popover components. Keep in mind that setupCalendar still needs to be called (passing optional defaults) using this method.

import Vue from 'vue';
import { setupCalendar, Calendar} from 'v-calendar'

// Remember to setup calendar (passing in defaults if needed)
setupCalendar({
  componentPrefix: 'vc',
  ...,
});

// Register component(s)
Vue.component('v-calendar', Calendar);

# CDN

<html>
  <head>
    <meta charset='utf-8'>
    <meta name='viewport' content='width=device-width, initial-scale=1, shrink-to-fit=no'>
    <meta http-equiv='x-ua-compatible' content='ie=edge'>
    <!--1. Link VCalendar CSS-->
    <link rel='stylesheet' href='https://unpkg.com/v-calendar/lib/v-calendar.min.css'>
  </head>
  <body>
    <div id='app'>
      <v-calendar></v-calendar>
      <v-date-picker :mode='mode' v-model='selectedDate' />
    </div>
    <!--2. Link Vue Javascript-->
    <script src='https://unpkg.com/vue/dist/vue.js'></script>
    <!--3. Link VCalendar Javascript (Plugin automatically installed)-->
    <script src='https://unpkg.com/v-calendar'></script>
    <!--4. Create the Vue instance-->
    <script>
      new Vue({
        el: '#app',
        data: {
          // Data used by the date picker
          mode: 'single',
          selectedDate: null,
        }
      })
    </script>
  </body>
</html>

# Custom Defaults

Custom defaults can be provided on initialization. Note that almost all of these defaults can be overridden by props on v-calendar or v-date-picker components.

Vue.use(VCalendar, {
  componentPrefix: 'vc', // Now use vc-calendar and vc-date-picker
  ...
})

Click here to see all defaults.