V-Calendar

Attributes

Attributes are what bring v-calendar to life. They are simply visual decorators that can be applied to specific calendar dates.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8

Quick Guide

Let's start by displaying a simple highlight on today's date.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
<v-calendar :attributes='attrs' />

export default {
  data() {
    return {
      attrs: [
        {
          key: 'today',
          highlight: true,
          dates: new Date(),
        },
      ],
    };
  },
};

For the simple example above, we used the following properties to build the attribute:

Property Description
key Uniquely identifies the attribute. This will come in handly later.
highlight Config for the highlighted region displayed on each date.
dates Dates used to display the attribute.

When simply assigning true to the highlight config (or any other attribute type except popovers), the currently active theme is used to display it. In this example, the theme is responsible to defining the default color (blue), fill mode, and content class for the highlight.

Here is how the default dot config would appear.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
export default {
  data() {
    return {
      attrs: [
        {
          key: 'today',
          dot: true,
          dates: new Date(),
        },
      ],
    };
  },
};

If you would like to use the active theme to display the attribute, just with a different color, pass a string with the desired color. Only included theme colors are supported (no hex values). Reference the theming guide for instructions on configuring your own theme.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
export default {
  data() {
    return {
      attrs: [
        {
          key: 'today',
          highlight: 'red',
          dates: new Date(),
        },
      ],
    };
  },
};

All attribute types (except popovers) allow using true or a theme color for its config value. Additionally, each attribute type supports its own unique configuration options using an object.

Click to learn more about the custom properties for highlights, dots, bars and popovers.

Finally, let's quickly see how simple it is to add a popover label (or tooltip) to the previous example. All we need to do is add a popover object to our attribute.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8







 
 
 







export default {
  data() {
    return {
      attrs: [
        {
          key: 'today',
          highlight: true,
          popover: {
            label: 'You just hovered over today\'s date!',
          },
          dates: new Date(),
        },
      ],
    };
  },
};

Attribute Types

The following attribute types are currently supported.

  • Highlights (Highlighted Background Regions)
  • Dot Indicators
  • Bar Indicators
  • Content Classes
  • Popovers

Attributes are defined as an array of objects (each object is a separate attribute). Any one or more of these types may be included in a single attribute object.

Furthermore, a single attribute may be displayed for single dates, date ranges and even complex date patterns. Some examples of complex patterns include:

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

Here is the basic structure of attributes:

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

...
data() {
  return {
    // Attributes are supplied as an array
    attributes: [
      // This is a single attribute
      {
        // An optional key can be used for retrieving this attribute later,
        // and will most likely be derived from your data object
        key: Any,
        // Attribute type definitions
        highlight: true,  // Boolean, String, Object
        dot: true,        // Boolean, String, Object
        bar: true,        // Boolean, String, Object
        content: 'red',   // Boolean, String, Object
        popover: { ... }, // Only objects allowed
        // Your custom data object for later access, if needed
        customData: { ... },
        // We also need some dates to know where to display the attribute
        // We use a single date here, but it could also be an array of dates,
        //  a date range or a complex date pattern.
        dates: new Date(),
        // You can optionally provide dates to exclude
        excludeDates: null,
        // Think of `order` like `z-index`
        order: 0
      }
    ];
  }
}

Using customData

The customData property is used to link your own custom data object to the attribute. The reason you might want to use this property becomes obvious as you begin to use the plugin. For example, if a user clicks on a calendar day that is displaying the attribute, you might want to react to that that click, so you will need to know that data associated with that attribute.

Using order

By default, attributes are ordered to display the most information possible. For example, when attributes with highlighted regions overlap, single date regions appear above date range regions, and date ranges with a later start date appear above those with an earlier start date.

If you would like to force an attribute to display above (or before) all others and override these rules, assign an order value greater than 0.

Highlights

As mentioned before, highlights may be configured using a simple boolean or string value.

// 1A. Uses the default blue theme
highlight: true   

// Uses the red theme
highlight: 'red'

These are the additional configuration options you may use for further highlight customization:

Property Type Description
color String Theme color.
fillMode String Color fill option: solid (default), light, none.
class String Any generic class you wish to apply to the background element of the highlight
contentClass String Any generic class you wish to apply to the content element of the highlight

Here is an example of using a more customized highlight to get a specific desired look.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
  // Customized highlight
  highlight: {
    color: 'purple',
    fillMode: 'light',
    contentClass: 'italic', // Class provided by TailwindCSS
  },

Dots

Dots may be configured using a simple boolean or string value.

// 1A. Uses the default blue theme
dot: true   

// Uses the red theme
dot: 'red'

These are the additional configuration options you may use for further dot customization:

Property Type Description
color String Theme color.
class String Any generic class you wish to apply to the dot dom element.
January 2018
S
M
T
W
T
F
S
31
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
<v-calendar
  :columns="$screens({ lg: 2 }, 1)"
  :from-date="new Date(2018, 0, 1)"
  :attributes="attributes"
  />

export default {
  data() {
    return {
      attributes: [
        {
          dot: {
            color: 'red',
            class: 'my-dot-class',
          },
          dates: [
            new Date(2018, 0, 1), // Jan 1st
            new Date(2018, 0, 10), // Jan 10th
            new Date(2018, 0, 22), // Jan 22nd
          ],
        },
        {
          dot: 'green',
          dates: [
            new Date(2018, 0, 4), // Jan 4th
            new Date(2018, 0, 10), // Jan 10th
            new Date(2018, 0, 15), // Jan 15th
          ],
        },
        {
          dot: 'purple',
          dates: [
            new Date(2018, 0, 12), // Jan 12th
            new Date(2018, 0, 26), // Jan 26th
            new Date(2018, 0, 15), // Jan 15th
          ],
        },
      ],
    };
  },
};

Bars

Bars may be configured using a simple boolean or string value. When more than one bar is dislayed per calendar day, they are equally spaced amongst each other. As a result, it might be a good idea to limit displaying up to 2 to 3 bars per day cell, as legibility can suffer.

// 1A. Uses the default blue theme
bar: true   

// Uses the red theme
bar: 'red'

These are the additional configuration options you may use for further bar customization:

Property Type Description
color String Theme color.
class String Any generic class you wish to apply to the bar dom element.
January 2018
S
M
T
W
T
F
S
31
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
<v-calendar
  :columns="$screens({ lg: 2 }, 1)"
  :from-date="new Date(2018, 0, 1)"
  :attributes="attributes"
  />

export default {
  data() {
    return {
      attributes: [
        {
          bar: {
            color: 'red',
            class: 'my-dot-class',
          },
          dates: [
            new Date(2018, 0, 1), // Jan 1st
            new Date(2018, 0, 10), // Jan 10th
            new Date(2018, 0, 22), // Jan 22nd
          ],
        },
        {
          bar: 'green',
          dates: [
            new Date(2018, 0, 4), // Jan 4th
            new Date(2018, 0, 10), // Jan 10th
            new Date(2018, 0, 15), // Jan 15th
          ],
        },
        {
          bar: 'purple',
          dates: [
            new Date(2018, 0, 12), // Jan 12th
            new Date(2018, 0, 26), // Jan 26th
            new Date(2018, 0, 15), // Jan 15th
          ],
        },
      ],
    };
  },
};

Popovers

There are 2 basic approaches to displaying popovers within attributes.

1. Labels

Labels are the basic tooltip-style popover. They are configured as simple strings. By default, these popovers display when the user hovers over the day content and additionaly are not interactive to the user.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
<template>
  <v-calendar
    :attributes='attributes'
    />
</template>

export default {
  data() {
    const todos = [
      {
        description: 'Take Noah to basketball practice.',
        isComplete: false,
        dates: { weekdays: 6 }, // Every Friday
        color: 'red',
      },
    ];
    return {
      incId: todos.length,
      todos,
    };
  },
  computed: {
    attributes() {
      return [
        // Attributes for todos
        ...this.todos.map(todo => ({
          dates: todo.dates,
          dot: {
            color: todo.color,
            class: todo.isComplete ? 'opacity-75' : '',
          },
          popover: {
            label: todo.description,
          },
          customData: todo,
        })),
      ];
    },
  },
};

For this example, we simply assigned a string to the popover.label property. This signals to v-calendar that it needs to display the label in a popover whenever the user hovers over the day content (or taps on mobile).

If we want to force the user to click on the day content in order to display the popover, we can set the popover's visibility property to "focus" or "click".

Focus

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
    ...
    popover: {
      label: todo.description,
      visibility: 'focus'
    }
    ...

Click

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
    ...
    popover: {
      label: todo.description,
      visibility: 'click'
    }
    ...

Also, you'll notice there is a small indicator next to the popover content row for the attribute. This is a simple indicator provided in order to help the user match up the popover content rows to the indicators in the calendar day cell. The indicator will try to coordinate the colors and shapes as closely as possible.

In the previous example, because a red dot was used, the indicator displays the same.

Here is how a bar or highlight would appear, respectively.

If you would like to hide the indicator, just set the hideIndicator property to true;

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
    ...
    popover: {
      label: todo.description,
      visibility: 'hover',
      hideIndicator: true,
    }
    ...

These are the additional configuration options you may use for further popover customization:

Property Type Description
label String Content to display in the popover.
labelClass String Class to apply to the label.
labelStyle Object Inline style to apply to the label.
hideIndicator Boolean Hides the indicator that appears to the left of the label.
visibility String Visibility mode for the popover ("hover-focus", "hover", "focus", "click", "visible", "hidden").
isInteractive Boolean Allows user to interactive with the popover contents. For example, this keeps the popover open when user hovers over the popover when visibility === "hover", instead of hiding it by default.

2. Scoped Slot

For a more customized approach you can insert your own "day-popover" custom scoped slot within v-calendar.

If you are not familiar with the convention of using scoped slots in Vue.js, you can reference the Vue docs or this post by alligator.io.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
<v-calendar
  :attributes="attributes"
  >
  <div slot="day-popover" slot-scope="">
    Using my own content now
  </div>
</v-calendar>

Notice that displaying static content here probably isn't going to help you much.

Now that you are providing your own popover, you need to display the attributes on your own. Fortunately, the following slot-scope props should provide you with everything you need to help you display content for your custom data.

Property Type Description
day Object The day object associated with the popover.
attributes Array All the attributes assigned for the associated day. Only attributes with 'truthy' values assigned to their popover key are passed in.
format Function Function for formatting dates. Accepts date: Date and mask: String arguments, respectively.
masks Object Set of format masks for the calendar.
updateLayout Function Call this function to force the popover to recalculate its layout. For example, making changes to elements within popover could cause it to grow or shrink. Calling this function will keep it positioned correctly.
hide Function Call this function to forcefully hide the popover.

Let's walk through the process of customizing the previous example. First, let's add a header to display the date for the popover.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
<v-calendar :attributes="attributes">
  <div slot="day-popover" slot-scope="{ day, format, masks }">
    <div class="text-xs text-gray-300 font-semibold text-center">
      {{ format(day.date, masks.dayPopover) }}
    </div>
  </div>
</v-calendar>

For the header, we use the format function to format the date for the current day, using the default dayPopover mask. Note: you could also just use your own custom mask.

Because this technique for displaying the header is common, you can extract the pre-formatted dayTitle property.

<v-calendar :attributes="attributes">
  <div slot="day-popover" slot-scope="{ day, dayTitle }">
    <div class="text-xs text-gray-300 font-semibold text-center">
      {{ dayTitle }}
    </div>
  </div>
</v-calendar>

Now, we just need to display the attributes for the day as well. We can do so by extracting the attributes array from the slot-scope expression. We'll use a simple list to display the attribute data.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
<v-calendar :attributes="attributes">
  <div
    slot="day-popover"
    slot-scope="{ day, dayTitle, attributes }">
    <div class="text-xs text-gray-300 font-semibold text-center">
      {{ dayTitle }}
    </div>
        <ul>
          <li
            v-for="{key, customData} in attributes"
            :key="key">
            {{ customData.description }}
          </li>
        </ul>
  </div>
</v-calendar>

Finally, if you wish to display indicators with your custom content, you can use the v-popover-row component included with the plugin. Just pass in the attribute for each row.

May 2019
S
M
T
W
T
F
S
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
<v-calendar :attributes="attributes">
  <div
    slot="day-popover"
    slot-scope="{ day, dayTitle, attributes }">
    <div class="text-xs text-gray-300 font-semibold text-center">
      {{ dayTitle }}
    </div>
    <v-popover-row
      v-for="attr in attributes"
      :key="attr.key"
      :attribute="attr">
      {{ customData.description }}
    </v-popover-row>
  </div>
</v-calendar>

← Date Picker →