---
title: "Vue Calendar Custom Header Example | Mobiscroll"
component: "Calendar"
framework: "Vue"
library_version: "6.2.0"
url: "https://demo.mobiscroll.com/vue/calendar/customizing-header"
---

# Custom Header - Vue Calendar demo

Customize the Vue date picker header — rearrange nav controls, add a today button, or add a week/month view switcher. For Vue and Nuxt.

- [Live demo](https://demo.mobiscroll.com/vue/calendar/customizing-header)
- [View SFC JS code on GitHub](https://github.com/acidb/mobiscroll-demos-vue/tree/main/src/demos/datepicker/calendar/customizing-header)
- [View SFC TS code on GitHub](https://github.com/acidb/mobiscroll-demos-vue-ts/tree/main/src/demos/datepicker/calendar/customizing-header)
- This demo in other frameworks: [JavaScript](https://demo.mobiscroll.com/calendar/customizing-header.md), [jQuery](https://demo.mobiscroll.com/jquery/calendar/customizing-header.md), [Angular](https://demo.mobiscroll.com/angular/calendar/customizing-header.md), [React](https://demo.mobiscroll.com/react/calendar/customizing-header.md)

## Description

You can customize how the header of calendar looks and how the components are arranged. Besides that you can also add custom functionality, like a segmented control that lets people switch between week and month view.

Use the `header` template for passing a custom header layout. There are predefined components - shorthands if you will - that can be used to assemble the header:

- **Navigation component** - `<MbscCalendarNav />`.
- **Today button** - `<MbscCalendarToday />`.
- **Previous month button** - `<MbscCalendarPrev />`.
- **Next month button** - `<MbscCalendarNext />`.

## What this demo shows

- The Datepicker calendar header can use the default layout, a custom arrangement, or be hidden completely.
- **Default header**: Displays the current month and year with previous and next navigation controls.
- **Month and year navigation**: Clicking the month and year label opens a picker for navigating directly to a specific month or year.
- **Previous and next controls**: Pages the calendar by one month in month view and one week in week view.
- **Custom header arrangement**: Centers `CalendarNav` and places `CalendarPrev` and `CalendarNext` on opposite sides using predefined calendar components.
- **Today button**: Adds a `CalendarToday` control between the navigation buttons in their default positions.
- **Week and month views**: Adds a segmented control with week and month icons for switching the calendar dynamically between the two views.
- **Selected date preview**: Displays the currently selected date in the header.

## Best for

- **Compact date pickers**: Hide the header when month and year navigation is unnecessary or space is limited.
- **Long-range date selection**: Open the month and year picker to reach dates that would require many previous or next navigation steps.
- **Current-date workflows**: Add a Today button when users frequently need to return to the current date.
- **Flexible date browsing**: Let users switch between week and month views when they need both a focused and a broader calendar view.
- **Selection confirmation**: Show the selected date in the header when users need a clear preview of their current choice.
- **Custom header layouts**: Rearrange the built-in navigation controls to fit the date picker's available space and surrounding interface.

## Tutorial

### Default header

The default header contains the two arrows on the far-right for previous and next months, while the current month indicator with the `MbscCalendarNav` component is placed to the far-left.

```vue
<template>
  <MbscDatepicker
    :controls="['calendar']"
    :calendarSize="2"
    calendarType="week"/>
</template>
```

### Custom header arrangement

You can reorder the controls and place the `MbscCalendarNav` in the middle with the two arrows - `MbscCalendarPrev` and `MbscCalendarNext` - to the sides.

```vue
<template>
  <MbscDatepicker :controls="['calendar']">
    <template #header>
      <MbscCalendarPrev cssClass="custom-prev" />
      <MbscCalendarNav cssClass="custom-nav" />
      <MbscCalendarNext cssClass="custom-next" />
    </template>
  </MbscDatepicker>
</template>
```

### Add a today button

You can also add a custom component, like a `MbscCalendarToday` button.

```vue
<template>
  <MbscDatepicker :controls="['calendar']">
    <template #header>
      <MbscCalendarNav />
      <div class="custom-buttons">
        <MbscCalendarPrev />
        <MbscCalendarToday />
        <MbscCalendarNext />
      </div>
    </template>
  </MbscDatepicker>
</template>
```

### Switch between week and month view

Use a segmented component for creating a view switcher.

```vue
<script setup>
const myCalendarType = ref('week')
</script>
<template>
  <MbscDatepicker :controls="['calendar']" :calendarType="myCalendarType" :calendarSize="2">
    <template #header>
      <MbscCalendarNav cssClass="custom-view-nav" />
      <div class="custom-view">
        <MbscSegmentedGroup v-model="myCalendarType">
          <MbscSegmented value="week" icon="material-date-range"></MbscSegmented>
          <MbscSegmented value="month" icon="material-event-note"></MbscSegmented>
        </MbscSegmentedGroup>
      </div>
    </template>
  </MbscDatepicker>
</template>
```

### Preview the selection

Above all that you can give instructions or show the selected `{value}` in the header

```vue
<template>
  <MbscDatepicker
    :controls="['calendar']"
    :calendarSize="2"
    calendarType="week"
    headerText="You selected {value}"
  >
</template>
```

## API used in this demo

- [`theme`](https://mobiscroll.com/docs/vue/datepicker/api#opt-theme) - option
- [`themeVariant`](https://mobiscroll.com/docs/vue/datepicker/api#opt-themeVariant) - option
- [`controls`](https://mobiscroll.com/docs/vue/datepicker/api#opt-controls) - option
- [`calendarSize`](https://mobiscroll.com/docs/vue/datepicker/api#opt-calendarSize) - option
- [`display`](https://mobiscroll.com/docs/vue/datepicker/api#opt-display) - option
- [`calendarType`](https://mobiscroll.com/docs/vue/datepicker/api#opt-calendarType) - option
- [`headerText`](https://mobiscroll.com/docs/vue/datepicker/api#opt-headerText) - option

## Code

### SFC JS

```vue
<script setup>
import {
  MbscCalendarNav,
  MbscCalendarNext,
  MbscCalendarPrev,
  MbscCalendarToday,
  MbscDatepicker,
  MbscSegmented,
  MbscSegmentedGroup,
  setOptions
} from '@mobiscroll/vue'
import { ref } from 'vue'

setOptions({
  theme: 'ios',
  themeVariant: 'light'
})

const myCalendarType = ref('week')
</script>

<template>
  <MbscDatepicker :controls="['calendar']" :calendarSize="2" display="inline" calendarType="week" />

  <MbscDatepicker :controls="['calendar']" display="inline">
    <template #header>
      <MbscCalendarPrev cssClass="custom-prev" />
      <MbscCalendarNav cssClass="custom-nav" />
      <MbscCalendarNext cssClass="custom-next" />
    </template>
  </MbscDatepicker>

  <MbscDatepicker :controls="['calendar']" display="inline">
    <template #header>
      <MbscCalendarNav />
      <div class="custom-buttons">
        <MbscCalendarPrev />
        <MbscCalendarToday />
        <MbscCalendarNext />
      </div>
    </template>
  </MbscDatepicker>

  <MbscDatepicker
    :controls="['calendar']"
    :calendarSize="2"
    :calendarType="myCalendarType"
    display="inline"
  >
    <template #header>
      <MbscCalendarNav cssClass="custom-view-nav" />
      <div class="custom-view">
        <MbscSegmentedGroup v-model="myCalendarType">
          <MbscSegmented value="week" icon="material-date-range"></MbscSegmented>
          <MbscSegmented value="month" icon="material-event-note"></MbscSegmented>
        </MbscSegmentedGroup>
      </div>
    </template>
  </MbscDatepicker>

  <MbscDatepicker
    :controls="['calendar']"
    :calendarSize="2"
    display="inline"
    calendarType="week"
    headerText="You selected {value}"
  />
</template>

<style>
.custom-buttons,
.custom-view,
.custom-nav {
  display: -webkit-box;
  display: -moz-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-flex: 1 0 auto;
  -moz-box-flex: 1;
  -ms-flex: 1 0 auto;
  flex: 1 0 auto;
}

.custom-buttons {
  -webkit-justify-content: flex-end;
  -moz-box-pack: end;
  -ms-flex-pack: end;
  justify-content: flex-end;
}

.custom-view,
.custom-nav {
  -webkit-justify-content: center;
  -moz-box-pack: center;
  -ms-flex-pack: center;
  justify-content: center;
}

.custom-view-nav .mbsc-calendar-title.mbsc-material {
  font-size: 16px;
}

.custom-view .mbsc-segmented {
  margin: 0;
}

.custom-view .mbsc-segmented.mbsc-material,
.custom-view .mbsc-segmented.mbsc-windows {
  padding: 0 2px;
}

.custom-view .mbsc-segmented .mbsc-segmented-button {
  padding: 0 1px;
}

.custom-view .mbsc-segmented .mbsc-icon {
  font-size: 20px;
}

.custom-view .mbsc-segmented-button.mbsc-windows {
  border: 0;
}
</style>
```

### SFC TS

```vue
<script setup lang="ts">
import {
  MbscCalendarNav,
  MbscCalendarNext,
  MbscCalendarPrev,
  MbscCalendarToday,
  MbscDatepicker,
  MbscSegmented,
  MbscSegmentedGroup,
  setOptions
} from '@mobiscroll/vue'
import { ref } from 'vue'

setOptions({
  theme: 'ios',
  themeVariant: 'light'
})

const myCalendarType = ref<'month' | 'week'>('week')
</script>

<template>
  <MbscDatepicker :controls="['calendar']" :calendarSize="2" display="inline" calendarType="week" />

  <MbscDatepicker :controls="['calendar']" display="inline">
    <template #header>
      <MbscCalendarPrev cssClass="custom-prev" />
      <MbscCalendarNav cssClass="custom-nav" />
      <MbscCalendarNext cssClass="custom-next" />
    </template>
  </MbscDatepicker>

  <MbscDatepicker :controls="['calendar']" display="inline">
    <template #header>
      <MbscCalendarNav />
      <div class="custom-buttons">
        <MbscCalendarPrev />
        <MbscCalendarToday />
        <MbscCalendarNext />
      </div>
    </template>
  </MbscDatepicker>

  <MbscDatepicker
    :controls="['calendar']"
    :calendarSize="2"
    :calendarType="myCalendarType"
    display="inline"
  >
    <template #header>
      <MbscCalendarNav cssClass="custom-view-nav" />
      <div class="custom-view">
        <MbscSegmentedGroup v-model="myCalendarType">
          <MbscSegmented value="week" icon="material-date-range"></MbscSegmented>
          <MbscSegmented value="month" icon="material-event-note"></MbscSegmented>
        </MbscSegmentedGroup>
      </div>
    </template>
  </MbscDatepicker>

  <MbscDatepicker
    :controls="['calendar']"
    :calendarSize="2"
    display="inline"
    calendarType="week"
    headerText="You selected {value}"
  />
</template>

<style>
.custom-buttons,
.custom-view,
.custom-nav {
  display: -webkit-box;
  display: -moz-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-flex: 1 0 auto;
  -moz-box-flex: 1;
  -ms-flex: 1 0 auto;
  flex: 1 0 auto;
}

.custom-buttons {
  -webkit-justify-content: flex-end;
  -moz-box-pack: end;
  -ms-flex-pack: end;
  justify-content: flex-end;
}

.custom-view,
.custom-nav {
  -webkit-justify-content: center;
  -moz-box-pack: center;
  -ms-flex-pack: center;
  justify-content: center;
}

.custom-view-nav .mbsc-calendar-title.mbsc-material {
  font-size: 16px;
}

.custom-view .mbsc-segmented {
  margin: 0;
}

.custom-view .mbsc-segmented.mbsc-material,
.custom-view .mbsc-segmented.mbsc-windows {
  padding: 0 2px;
}

.custom-view .mbsc-segmented .mbsc-segmented-button {
  padding: 0 1px;
}

.custom-view .mbsc-segmented .mbsc-icon {
  font-size: 20px;
}

.custom-view .mbsc-segmented-button.mbsc-windows {
  border: 0;
}
</style>
```

## Implementation notes

- Use `controls: ['calendar']` and `display: 'inline'`; the compact multi-row examples add `calendarType: 'week'` and `calendarSize: 2`.
- **Default header**: no extra option needed - it renders the nav label on the left and the prev/next arrows on the right.
- **Custom arrangement**: pass `renderCalendarHeader` (Angular: `calendarHeaderTemplate`, Vue: `#header` slot) returning custom markup that composes the predefined header sub-components - `mbsc-calendar-nav` (Vue: `MbscCalendarNav`, React: `CalendarNav`), `mbsc-calendar-prev`/`mbsc-calendar-next` (Vue: `MbscCalendarPrev`/`MbscCalendarNext`, React: `CalendarPrev`/`CalendarNext`) - in any order/position.
- **Today button**: include `mbsc-calendar-today` (Vue: `MbscCalendarToday`, React: `CalendarToday`) alongside the prev/next controls inside the same custom header markup.
- `calendarType` can be switched at runtime between `'week'` and `'month'`. React/Vue/Angular update it as a controlled value (`useState`, `v-model`, `[(ngModel)]`) bound to the datepicker's `calendarType` prop; JS/jQuery call `.setOptions({ calendarType: 'week' | 'month' })` on the instance.
- **Selected-date preview**: set `headerText` to a template string containing `{value}` (e.g. `'You selected {value}'`) - it's substituted with the current selection and rendered in the header automatically, no custom renderer needed.
- To hide the header entirely, return empty/no markup from `renderCalendarHeader` - pair with a compact layout when month/year navigation isn't needed.

## Run it in your project

1. If not signed up yet, or don't own a license, you can [start a free trial](https://mobiscroll.com/starttrial).

2. Clone the repository:

   ```
   git clone https://github.com/acidb/mobiscroll-demos-vue.git
   ```

3. If not installed yet, install the Mobiscroll CLI from NPM:

   ```
   npm install -g @mobiscroll/cli
   ```

4. Config Mobiscroll - open a terminal window in the root directory and run:

   ```
   mobiscroll config vue
   ```

5. Install dependencies - open a terminal window in the root directory and run:

   ```
   npm install
   ```

6. Run the project:

   ```
   npm run dev
   ```

On a trial, add `--trial` to the config command: `mobiscroll config vue --trial`.

Running a demo locally requires a Mobiscroll trial or a license; setup is per framework at https://mobiscroll.com/docs/vue/getting-started/installation

## Related demos

- Previous: [Themes — iOS, Material & Windows](https://demo.mobiscroll.com/vue/calendar/themes-ios-material-windows.md) - Style the Vue calendar date picker with iOS, Material, or Windows themes — switch light/dark mode, use the theme builder, or apply custom CSS.
- Next: [Mark Days with Custom Shapes](https://demo.mobiscroll.com/vue/calendar/customize-marked-day-shapes.md) - Add custom-shaped day markers to a Vue calendar date picker — use the marked option for colored dots, then override styles.