feat(datetime): add ability to specify custom colors for specific dates

[averyjohnston]

Pull request checklist

Please check if your PR fulfills the following requirements:

• Tests for the changes have been added (for bug fixes / features)
• Docs have been reviewed and added / updated if needed (for bug fixes / features)
  • Some docs updates need to be made in the ionic-docs repo, in a separate PR. See the contributing guide for details.
• Build (npm run build) was run locally and any changes were pushed
• Lint (npm run lint) has passed locally and any fixes were made for failures

Pull request type

Please check the type of change your PR introduces:

• Bugfix
• Feature
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no api changes)
• Build related changes
• Documentation content changes
• Other (please describe):

What is the current behavior?

Developers have no way of highlighting specific days on the calendar picker with custom styles.

Issue URL: Resolves #25832

What is the new behavior?

Adds a new property, highlightedDates, which allows certain dates in the calendar view to be styled with custom text and/or background colors. This can be in the form of either an array of specific dates and their colors, or a callback that takes an ISO string and returns the colors to use.

As a side effect, all styles around focused/selected/"today" dates have been consolidated into the new .calendar-day-highlight element. A new element was necessary in order to programmatically apply background colors, since inline styles can't be used with pseudo-elements.

Note that this feature does not include the ability to show details about events associated with highlighted dates, such as birthdays or scheduled meetings. This is intentional as ion-datetime is only intended to concern itself with date selection, and any additional context should be an application-level detail provided in a separate UI.

Playgrounds/docs updates are made in a separate PR: ionic-team/ionic-docs#2769

Does this introduce a breaking change?

• Yes
• No

Other information

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[sean-perkins]

Small recommended changes, but this feature looks great testing locally. Nice work!

[averyjohnston]

Docs PR created: ionic-team/ionic-docs#2769

[liamdebeasi]

Great job!

[seatechdev]

Just looked at the new release. It is amazing! Thanks for adding this so quickly.

[creatxrgithub]

its docs: https://ionicframework.com/docs/api/datetime#highlighting-specific-dates

it seems that it has only two properties "textColor" and "backgroundColor".

{
          date: '2023-01-10',
          textColor: '#09721b',
          backgroundColor: '#c8e5d0',
},

is it possible to attach text? so that i could do :
#26361
or
#25832

[ChanakaWeerasinghe]

@averyjohnston @seatechdev @creatxrgithub @sean-perkins @liamdebeasi

its docs: https://ionicframework.com/docs/api/datetime#highlighting-specific-dates

it seems that it has only two properties "textColor" and "backgroundColor".

{
          date: '2023-01-10',
          textColor: '#09721b',
          backgroundColor: '#c8e5d0',
},
is it possible to attach text? so that i could do :
https://github.com/ionic-team/ionic-framework/issues/26361
or
https://github.com/ionic-team/ionic-framework/issues/25832

[gyoung-tf]

Sorry to come back to this PR after literally years, but I'm interested in understanding why this PR is considered to resolve #25832. Showing dots underneath each date is I think a pretty standardised way to indicate the existence (and sometimes number) of events on each date (used by both iOS and Android calendars), and in my opinion changing the colours of the dates doesn't convey that same information (at least not 'intuitively' i.e in a way that users are already familiar with ). I understand that the philosophy of ion-datetime is more focused on date selection rather than conveying information about the dates, but I think that the existence of events is important information to convey to the user as part of their date selection.

[liamdebeasi]

I don't work for Ionic anymore, but I worked on this feature during the planning stages. We wanted a clear separation between date selection (what Ionic has now) and calendar selection (think of calendar.google.com). While seemingly similar, a date picker and a calendar picker have diverging feature sets, and we didn't think it would be good to have those two use cases combined into a single component. Additionally, the work required to have a standalone ion-calendar component was more than we were willing to take on at the time given the size of the team and the other areas of the project that required our attention.

We saw a date picker as focusing on generic dates (I.e. June 13, 2025) and a calendar picker focusing more on the context of the date (e.g. "I have a dentist appointment on June 13, 2025"). However, Ionic devs wanted some level of context awareness, so this feature was a compromise where users were able to provide context without ion-datetime having to be concerned with the specifics. We recognized that it might not be a great fit for every Ionic dev, but in the years since this was released it has proven to be a useful feature for most Ionic devs. Hope this clarifies things!

[seatechdev]

I think that I had originally requested this feature i.e. ability to color code dates, because I didn't want to use a third party calendar component. Later on I determined that I didn't really need an out of box calendar component from Ionic. Instead, I was able to use the current date time component and modify the presentation layer with ng-if statements.