Angular Material Datepicker: Complete Guide

Adding the Angular Material Datepicker to Your Project

When building Angular applications, one of the most frequently needed form controls is a datepicker. Rather than pulling in non-Angular libraries like the jQuery datepicker, the Angular Material library provides a fully native, responsive datepicker component that is thoroughly tested.

The Angular Material datepicker comes with a rich set of features, many of which may not be immediately obvious. In this guide, we'll walk through everything from basic setup to advanced customization.

What We'll Cover

Here's the list of topics we'll explore in this guide:

• Steps to get the Angular Material Datepicker installed and running
• Attaching a modal calendar to the datepicker
• Triggering the calendar dialog on input click
• Customizing the mat-datepicker-toggle icon
• Blocking manual date entry
• Choosing the initial view mode for the calendar
• Setting a custom starting date
• Restricting the selectable date range
• Using matDatepickerFilter for custom date validation
• Styling the calendar appearance
• Applying custom styles to particular dates
• Improving the experience on mobile devices
• Using the calendar inline without an input field
• Wrap-up and key takeaways

This post is part of our broader series on Angular Material; you can find the complete list of articles here.

Let's dive straight into the details.

Setting Up the Angular Material Datepicker

A standard datepicker in Angular Material looks like this:

This component is built from three distinct parts:

• A text input that accepts manual date entry
• A modal calendar dialog for visual date selection
• A calendar icon that toggles the calendar dialog open and closed

We'll construct a datepicker by adding these elements one at a time to understand how they interconnect.

Starting with just the input field:

At this stage, it's a standard Angular Material input with no date-specific behavior. The field is bound to a form control called releasedAt using the formControlName directive from Angular Forms.

Notice the outline appearance, which gives the input its distinctive border. Also note the matInput directive — without it, the input field won't function properly within the Material framework.

Attaching a Modal Calendar

Now, we'll add a modal calendar next to the input. The [matDatepicker] directive is used to link the input field with the modal element.

At this point, you won't see any change yet, as the calendar is hidden by default. To open or close it, we need a toggle button. We'll add it as a suffix to the input field and connect it to the calendar:

The [for] directive on the toggle is what binds it to the datepicker instance.

With that, the basic datepicker is fully operational — you can open the calendar and pick a date. However, this only scratches the surface. Let's explore the many configuration options available.

Opening the Calendar on Input Click

A common request is to have the calendar dialog appear automatically when the input field is clicked. This can be achieved with a simple event handler that calls the calendar.open() method.

Customizing the mat-datepicker-toggle Icon

It's possible to alter the position and appearance of the toggle button. The calendar icon appears on the right side of the input because of the matSuffix directive, which is a Material input configuration that places the child element at the end of the field.

If you'd prefer the icon on the left, simply swap matSuffix for matPrefix. Here's the result:

Beyond positioning, you can also swap out the default icon. While the calendar icon is the standard, the Material icon library offers many alternatives that might better suit your design. Here's a collection of calendar icons to choose from.

To use a different icon, you'll need to add it between the toggle tags along with a specific directive. Here's how:

Note the matDatepickerToggleIcon directive, which is essential for the custom icon to render correctly. The updated calendar will appear as follows:

Preventing Manual Date Entry

In many cases, you'll want to allow both manual typing and calendar selection. However, you might need to disable typing in certain scenarios, such as a read-only display.

Simply disabling the input field will also disable the toggle button and calendar, making the entire component inert. To keep the calendar usable while blocking manual input, you need to explicitly override the disabled state on both elements:

This requires setting the disabled property to false on the toggle button and the calendar, even when the input is disabled.

Selecting the Initial Calendar View

By default, the calendar opens in the monthly view centered on the current date or the set value. This is ideal for most cases, but for dates like birthdays, it might be more logical to start with the year or decade view to help users navigate to a different year.

The startView property lets you change the initial view. Here's the yearly view result:

Setting startView to multi-year gives you the following view:

Setting the Calendar's Starting Date

You can also specify a starting date for the calendar that differs from the form control's value. First, define a member variable in your component:

startDate = new Date(2010, 0, 1)

Then, pass it to the datepicker as shown below.

Limiting Selectable Date Ranges

There are times when you need to constrain which dates are valid. To set a minimum and maximum date, define two bound properties in your component:

minDate = new Date(2010, 0, 3); 
maxDate = new Date(2010, 0, 15);

The [min] and [max] directives are then applied to the matInput element:

Here's how the datepicker appears with these limits in place:

Dates that fall outside the allowed range are greyed out and cannot be selected.

Custom Date Validation with matDatepickerFilter

For more granular control, you can define custom validation logic. For example, to restrict selection to Mondays only, you would create a filter function:

This function returns true for Mondays and false for all other days. Wire it into the datepicker with the [matDatepickerFilter] directive:

The result allows only Monday dates to be selected, as shown:

Customizing the Calendar's Color Palette

The datepicker uses your theme's primary palette by default for highlighting. It's easy to switch to the accent or warn palettes.

To use the accent palette, set the color property to accent:

Here's what that looks like:

If you need the warning palette, use warn as the color property instead.

Adding Custom Styles to Specific Dates

For more advanced styling, you might want to target certain dates. To achieve this, you can use a date class function to assign CSS classes based on the date. For example, to highlight the first day of each month in the month view, you'd create a function that returns the highlight-date class for those dates only.

The returned class(es) are then applied conditionally. Connect the function to the datepicker via the [dateClass] directive:

In the monthly view, the first day of each month will be visually distinct, as demonstrated:

Enhancing the Datepicker for Mobile

The default datepicker works on mobile but can feel cramped. For a more touch-friendly interface, especially if most of your users are on mobile, you can enable the larger view by setting the touchUi property to true.

This makes the calendar dialog significantly larger and easier to interact with on a touchscreen:

Using the Standalone Calendar Component

In some cases, you don't need an input field at all — perhaps you want an inline calendar so the user can pick a date directly on the page. The mat-calendar component handles this scenario.

Here's how you implement it:

The result is a fully functional inline calendar:

Recap

We've covered a lot in this guide. If you're looking to dive even deeper into Angular Material, the Angular Material In Depth course offers extensive coverage of many more components and best practices:

Feel free to leave any questions or comments below. To stay updates on future posts about Angular Material and other Angular topics, consider subscribing to the newsletter.

For those just starting out with Angular, the Angular for Beginners Course is a great resource: