Welcome to V-Calendar

V-Calendar is a clean and lightweight 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 styles and popovers for simple tooltips and even custom slot content.

Any single attribute may contain one of each object and can be displayed for single dates, date ranges and even complex date patterns like every other Friday, the 15th of every month or the last Friday of every other month.

It has date picker support out of the box with single date, multiple date and date range selection modes. Because v-date-picker is simply a wrapper for v-calendar, both can be extensively customized using props, slots and theme styling, just like v-calendar. And of course, V-Calendar is responsive and mobile friendly. For example, it supports touch swipes for month navigation.

Calendar

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

Single or double paned
Can be expanded to fill the width of its container
Header title can be left, right or center-aligned
Slot support for custom header and header subcomponents
Navigation transitions (horizontal slide, vertical slide, fade)

Along with the calendar panes, v-calendar employs a semantic-inspired navigation pane when the header title is hovered or focused by the user.

Attributes

Attributes are the most important concept to understand. They provide a powerful way to communicate visual information to your users quickly and effectively. Fortunately, they are also easy to specify.

What to display

The first thing to understand about attributes is what they are capable of displaying.

Highlights
Dot Indicators
Bar Indicators
Popovers
Content Styles

For now, let's just start by displaying a simple highlight on today's date.

<template>
  <v-calendar :attributes='attrs'>
  </v-calendar>
</template>

export default {
  data() {
    return {
      attrs: [
        {
          key: 'today',
          highlight: {
            backgroundColor: '#ff8080',
            // Other properties are available too, like `height` & `borderRadius`
          },
          dates: new Date(2018, 0, 1)
        }
      ],
    };
  },
};

To add some contrast to the highlighted date, we can use a content style, which is simply a style object that gets applied to the day content text.

export default {
  data() {
    return {
      attrs: [
        {
          key: 'today',
          highlight: {
            backgroundColor: '#ff8080',
          },
          // Just use a normal style
          contentStyle: {
            color: '#fafafa',
          },
          dates: new Date(2018, 0, 1)
        },
      ],
    };
  },
};

Finally, let's see how simple it is to add a popover label (or tooltip) to the calendar when this highlight is hovered over. To do that, we just need to add a popover section to our attribute.

export default {
  data() {
    return {
      attrs: [
        {
          key: 'today',
          dates: new Date(2018, 0, 1),
          highlight: {
            backgroundColor: '#ff8080',
          },
          // Just use a normal style
          contentStyle: {
            color: '#fafafa',
          },
          // Our new popover here
          popover: {
            label: 'You just hovered over today\'s date!',
          }
        },
      ],
    };
  },
};

Where to display

The second aspect of attributes is specifying where to display them. In the previous example, we saw that all we had to do was use a simple date object assigned to the dates property. Note that we aren't limited to using single date or date range objects. We can also use an array of dates.

  ...
  dates: [ new Date(2018, 0, 1), new Date(2018, 0, 15) ]
  ...

Or date ranges...

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

Or date patterns.

  ...
  dates: { weekdays: [1, 7] } // On the weekends
  ...

Date Picker

The v-date-picker component is a flexible date picker component wrapper around v-calendar, which means it supports all props and events that v-calendar does. Using the mode prop, it is capable of 3 selection modes:

Single dates
Multiple dates
Date ranges

Date pickers can be displayed inline or as a popover for an input element which can be classed or styled.

<v-date-picker
  mode='range'
  v-model='selectedDate'
  show-caps>
</v-date-picker>

export default {
  data() {
    return {
      selectedDate: {
        start: new Date(2018, 0, 9),
        end: new Date(2018, 0, 18)
      }
    };
  },
};

Also, a custom slot element can be used to display your own input element. This example uses Buefy for a custom styled input component.

<v-date-picker
  mode='single'
  v-model='selectedDate'>
  <b-field :type='inputState.type' slot-scope='props'>
    <b-input
      type='text'
      icon='calendar'
      :value='props.inputValue'
      :placeholder='inputState.message'
      @change.native='props.updateValue($event.target.value)'
      expanded>
    </b-input>
    <p
      class='control'
      v-if='selectedValue'>
      <a
        :class='["button", inputState.type]'
        @click='selectedValue = null'>
        Clear
      </a>
    </p>
  </b-field>
</v-date-picker>

export default {
  data() {
    return {
      selectedDate: new Date(2018, 0, 10)
    };
  },
  computed: {
    inputState() {
      if (!this.selectedValue) {
        return {
          type: 'is-danger',
          message: 'Date required.',
        };
      }
      return {
        type: 'is-primary',
        message: '',
      };
    },
  },
};

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

Explicitly via min-date or max-date

<!--Set minimum date-->
<v-date-picker
  :min-date='new Date()'
  v-model='selectedDate'>
</v-date-picker>

Explicitly via disabled-dates (still works with min-date or max-date).

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

Implicitly via available-dates. Any dates not included in available-dates are disabled.

<!--Today is the minimum date (null denotes infinite date)-->
<v-date-picker
  :available-dates='{ start: new Date(), end: null }'
  v-model='selectedDate'>
</v-date-picker>

Formatting & Parsing

Dates are formatted and/or parsed for the following component sections:

Component(s)	Target Area	Default Format
`v-calendar` `v-date-picker`	Calendar header title	MMMM YYYY
`v-calendar` `v-date-picker`	Weekday headers	W
`v-calendar` `v-date-picker`	Month labels in navigation dropdown	MMM
`v-date-picker`	Input element when `is-inline === false`	L
`v-date-picker`	Day popover when user hovers selected date	WWW, MMM D, YYYY

By default, v-calendar uses Javascript's Internalization API (which is increasingly well supported) to derive the month and weekday names for the user's locale. This helps keep the package size to a minimum while utilizing an API that should only improve with time. It also uses the most appropriate long date format (L) for that locale (derived from moment.js).

To use your own custom formats, configure and pass the formats object

As a prop to v-calendar or v-date-picker

<v-date-picker
  :formats='formats'
  v-model='myDate'>
</v-date-picker>

export default {
  data() {
    return {
      myDate: null,
      formats: {
        title: 'MMMM YYYY',
        weekdays: 'W',
        navMonths: 'MMM',
        input: ['L', 'YYYY-MM-DD', 'YYYY/MM/DD'], // Only for `v-date-picker`
        dayPopover: 'L', // Only for `v-date-picker`
        data: ['L', 'YYYY-MM-DD', 'YYYY/MM/DD'] // For attribute dates
      }
    }
  }
}

As a default when using VCalendar

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

Vue.use(VCalendar, {
  formats: {
    title: 'MMMM YYYY',
    weekdays: 'W',
    navMonths: 'MMM',
    input: ['L', 'YYYY-MM-DD', 'YYYY/MM/DD'],
    dayPopover: 'L',
    data: ['L', 'YYYY-MM-DD', 'YYYY/MM/DD']
  }
})

Parsing dates for input element

You'll notice an array was used to specify the formats for v-date-picker's input element. This is because it uses the supplied format(s) to parse, as well as display, the selected date. The first supplied format is used to display the date selection, while all formats can be used 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 format to parse the date, but will also try to parse formats 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 format settings.

Format Tokens

Use the following tokens to configure your custom formats:

Category	Token	Output
Month	`M`	1, 2, ..., 12
	`MM`	01, 02, ..., 12
	`MMM`	Jan, Feb, ..., Dec
	`MMMM`	January, February, ..., December
Day of Month	`D`	1, 2, ..., 31
	`DD`	01, 02, ..., 31
	`Do`	1st, 2nd, ..., 31st
Day of Week	`d`	1, 2, ..., 7
	`d`	1, 2, ..., 7
	`dd`	01, 02, ..., 07
	`W`	S, M, ..., S
	`WW`	Su, Mo, ..., Sa
	`WWW`	Sun, Mon, ..., Sat
	`WWWW`	Sunday, Monday, ..., Saturday
Year	`YY`	70, 71, ... 69
	`YYYY`	1970, 1971, ..., 2069
Long Date	`L`	01/21/1983 (en-US), 21/01/1983 (en-GB), ..., 1983/01/21 (civilized)

I19n

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.

At the moment, this API still cannot provide all recommended default settings per locale (such as 'first day of the week'), so those settings are provided out of the box for a reasonable number of locales, with a decent fallback for those locales that aren't included.

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.

1 Install via npm

npm install v-calendar

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';
import 'v-calendar/lib/v-calendar.min.css';

// Use v-calendar, v-date-picker & v-popover components
Vue.use(VCalendar, {
  firstDayOfWeek: 2,  // Monday
  ...,                // ...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'
import 'v-calendar/lib/v-calendar.min.css';

// Remember to setup calendar (passing in defaults if needed)
setupCalendar({
  firstDayOfWeek: 2,  // Monday,
  ...,                // ...other defaults
});

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

3 Reference in your component templates

<template>
  <v-calendar
    is-double-paned>
  </v-calendar>
  <v-date-picker
    mode='single'
    v-model='selectedValue'>
  </v-date-picker>
</template>

<script>
export default {
  data() {
    return {
      selectedValue: new Date(),
    };
  },
};
</script>

Or use a 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'></v-date-picker>
    </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>

Polyfill

v-calendar is transpiled for ES5, but it still needs a polyfill for Array.prototype.find (<= IE11) or even Intl (Javascript's internationalization object, <= IE10) if you wish to target older browsers. Two options for accomplishing this are:

Easy way: Insert the following script into your html before loading v-calendar. The polyfill will get loaded automatically only if the browser needs it.

<script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=Array.prototype.find,Intl" />

In Node/Browserify/Webpack environments, use babel-polyfill to insert the polyfill for you.

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, {
  firstDayOfWeek: 2, // Set first day of week to Monday
  ...
})

Property Name	Type	Description	Default
`locale`	String	Locale identification in language-region format. Not all regions supported.	`undefined`
`componentPrefix`	String	Custom prefix to use for plugin components. Replace if `v-calendar` and `v-date-picker` interfere with other component libraries.	`"v"`
`firstDayOfWeek`	Number	Day number for the first day of the week (1: Sun - 7: Sat)	`1`
`formats`	Object	Formats to use when display and parsing dates for various calendar sections	Reference code
`navVisibility`	String	Visibility state for calendar navigation panel (`"focus"`, `"hover"`, `"visible"`, `"hidden"`)	`"focus"`
`titlePosition`	String	Position of the title in the header (`"left"`, `"center"`, `"right"`)	`"center"`
`titleTransition`	String	Transition type for title when navigating to a new page (`"slide-h"`, `"slide-v"`, `"fade"`, `"none"`)	`"slide-h"`
`weeksTransition`	String	Transition type for weeks when navigating to a new page (`"slide-h"`, `"slide-v"`, `"fade"`, `"none"`)	`"slide-h"`
`paneWidth`	Number	Width of a single pane, in pixels.	`256`
`showLinkedButtons`	Boolean	When calendar `is-linked` and `!is-vertical`, show the inner header navigation buttons that are usually hidden.
`datePickerUpdateOnInput`	Boolean	Update the picker value after every `input` event.	`false`
`datePickerTintColor`	String	Background color of the selected and dragged highlighted regions (`opacity: 0.5` for dragged). This setting is overridden by `select-attribute` and `drag-attribute` if specified.	`"#66B3CC"`
`datePickerShowCaps`	Boolean	Show caps and the end of the highlighted and dragged regions when `mode === "range"`	`false`
`datePickerShowDayPopover`	Boolean	Show popover for dragged and selected regions	`true`
`popoverExpanded`	Boolean	Popover wrapper for input or slot is expanded to the full width of its container.	`false`
`popoverDirection`	String	Direction that popover displays relative to input or slot element (`"bottom"`, `"top"`, `"left"`, `"right"`)	`"bottom"`
`popoverAlign`	String	How the popover is aligned relative to input or slot element (`"left"`, `"right"`, `"top"`, `"bottom"'`)	`"left"`
`popoverVisibility`	String	Visibility state of the popover (`"hover"`, `"focus"`, `"hidden"`, `"visible"`)	`"hover"`
`popoverContentOffset`	String	Distance that the popover content is offset from the input or slot element	`"10px`
`popoverKeepVisibleOnInput`	Boolean	Keep the popover visible after a valid input has been selected	`false`
`maxSwipeTime`	Number	Maximum time in milliseconds allowed for a swipe gesture to complete	`300`
`minHorizontalSwipeDistance`	Number	Minimum distance in pixels allowed for a horizontal swipe gesture	`60`
`maxVerticalSwipeDistance`	Number	Maximum distance in pixels allowed for a horizontal swipe gesture	`80`
`maxTapTolerance`	Number	Maximum distance in pixels allowed for a tap between `touchstart` and `touchend` events	`0`
`maxTapDuration`	Number	Maximum time in milliseconds allowed for a tap between `touchstart` and `touchend` events	`200`

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
gitbook/images		gitbook/images
styles		styles
.gitignore		.gitignore
.netlify		.netlify
.prettierignore		.prettierignore
README.md		README.md
SUMMARY.md		SUMMARY.md
api.md		api.md
attributes.md		attributes.md
bars.md		bars.md
book.json		book.json
data.md		data.md
datepicker.md		datepicker.md
dots.md		dots.md
highlights.md		highlights.md
layout.md		layout.md
migration-guide.md		migration-guide.md
package-lock.json		package-lock.json
package.json		package.json
popovers.md		popovers.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Welcome to V-Calendar

Calendar

Attributes

What to display

Where to display

Date Picker

Formatting & Parsing

Parsing dates for input element

Format Tokens

I19n

Installation

1 Install via npm

2 Import and use VCalendar

2A. Plugin Method (Recommended)

2B. Components Method

3 Reference in your component templates

Or use a CDN

Polyfill

Custom Defaults

About

Releases

Packages

Languages

nathanreyes/v-calendar-docs

Folders and files

Latest commit

History

Repository files navigation

Welcome to V-Calendar

Calendar

Attributes

What to display

Where to display

Date Picker

Formatting & Parsing

Parsing dates for input element

Format Tokens

I19n

Installation

1 Install via npm

2 Import and use VCalendar

2A. Plugin Method (Recommended)

2B. Components Method

3 Reference in your component templates

Or use a CDN

Polyfill

Custom Defaults

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages