feat(datepicker): added onVisibleRangeChange callback

[IvanKalinin]

📝 Description

Added onPageChange callback to datepicker api. Useful to determine the current month after clicking next/previous trigger and, for example, load events or different data based on the current calendar page/month.

⛳️ Current behavior (updates)

N/A

🚀 New behavior

Triggers onPageChange callback on clicking next/previous trigger

💣 Is this a breaking change (Yes/No):

No

📝 Additional Information

N/A

[changeset-bot]

⚠️ No Changeset found

Latest commit: 238da46

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
zag-nextjs	Error		Dec 15, 2025 5:04am
zag-solid	Ready	Preview	Dec 15, 2025 5:04am
zag-svelte	Ready	Preview	Dec 15, 2025 5:04am
zag-vue	Ready	Preview	Dec 15, 2025 5:04am
zag-website	Error		Dec 15, 2025 5:04am

[segunadebayo]

Thanks for contributing this. I was wondering if there was an alternative name to “onPageChange”, given the word “page” doesn’t feel intuitive for a date picker.

Wondering if “onNavigate” or a combo of “onPrevTriggerClick” + “onNextTriggerClick” would work.

[IvanKalinin]

Thanks for contributing this. I was wondering if there was an alternative name to “onPageChange”, given the word “page” doesn’t feel intuitive for a date picker.

Wondering if “onNavigate” or a combo of “onPrevTriggerClick” + “onNextTriggerClick” would work.

Do you want me to rename it to onNavigate?

[IvanKalinin]

@segunadebayo Did you make a decision?
Do you want me to rename the callback to onNavigate? Or it is good to go as is, where onPageChange makes the perfect sense to me, since the codebase already uses "page" as the entity name. (e.g., getNextPage, getPreviousPage)

zag/packages/machines/date-picker/src/date-picker.machine.ts

Lines 9 to 13 in 3dbfe4a

	getEndDate,
	getNextPage,
	getNextSection,
	getPreviousPage,
	getPreviousSection,

It also makes sense in terms of a physical calendar with pages

[segunadebayo]

Yes, you might be right @IvanKalinin

I was wondering if it's better to attach the onClick to the prev/next trigger in your userland code instead of adding a new prop.

The name can be misleading since there might be more scenarios where users might want onPageChange to be fired, for example, when the month/year select is used.

[IvanKalinin]

@segunadebayo Is there an ETA for when the PR can be merged in Zag and delivered to the Ark UI?
I need the feature to replace a few of my legacy components with the Ark Datepicker.

[segunadebayo]

Did you see my message above? @IvanKalinin

[IvanKalinin]

@IvanKalinin, I guess I just misunderstood you.
Although the "page" term makes perfect sense to me, I replaced it with onNextTriggerClick and onPrevTriggerClick if you like this more.

[IvanKalinin]

@segunadebayo After a little bit more thinking, I decided to implement the feature under the onVisibleRangeChange callback.
Should be clear enough.