---
title: "Pre-selecting a calendar date using URL parameters"
date: 2026-04-23
author: "GravityKit"
link: "https://www.gravitykit.com/docs/gravitycalendar/url-parameter-initial-calendar-date/"
---

Learn how to automatically navigate to a specific date when someone visits your calendar by adding a URL parameter.

## What you'll learn

This guide shows you how to add a code snippet that allows you to pre-select a date on your GravityCalendar using a URL parameter. This is useful for sharing links to specific events or dates.

## Before you begin

- You need [GravityCalendar](https://www.gravitykit.com/extensions/calendar/) installed and activated
- You should have at least one [calendar feed](https://www.gravitykit.com/docs/gravitycalendar/creating-a-calendar/) configured

## How it works

When someone visits a URL like `https://example.com/events/?calendar_date=2025-03-15` , the calendar will automatically open to March 15, 2025.

## Installation

- Copy the snippet
- [Add it to your site](https://www.gravitykit.com/docs/gravityview/customizing-your-views/where-to-put-code-samples/)

```
/**
 * GravityCalendar - URL Parameter Initial Date Support
 *
 * This snippet allows users to pre-select a calendar date via URL parameter.
 *
 * Usage Examples:
 * - ?calendar_date=2025-03-01
 * - ?calendar_date=2025-03-15
 * - ?calendar_date=2025-12-25
 */

/**
 * The URL parameter name to use for the initial date.
 *
 * Example: If set to 'calendar_date', use ?calendar_date=2025-03-01 in the URL
 * Example: If set to 'start_date', use ?start_date=2025-03-01 in the URL
 */
define( 'GRAVITYCALENDAR_DATE_URL_PARAM', 'calendar_date' );

add_filter( 'gravityview/calendar/options', 'gravitycalendar_add_initial_date_from_url', 10, 3 );
add_filter( 'gravityview/calendar/extra_options', 'gravitycalendar_set_navigate_to_current_from_url', 10, 3 );

/**
 * Get and validate date from URL parameter.
 *
 * This helper function extracts the date from the URL, validates the format,
 * and ensures it's a real date. Returns the validated date string or false.
 *
 * @since TBD
 *
 * @return string|false The validated date string (YYYY-MM-DD) or false if invalid/missing.
 */
function gravitycalendar_get_date_from_url() {

	/**
	 * Check if the URL has our date parameter.
	 */
	$url_param_name = GRAVITYCALENDAR_DATE_URL_PARAM;

	// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Reading URL parameter for display only.
	if ( ! isset( $_GET[ $url_param_name ] ) ) {
		return false;
	}

	/**
	 * Get the date from the URL and clean it up for security.
	 */
	// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Reading URL parameter for display only.
	$user_provided_date = sanitize_text_field( wp_unslash( $_GET[ $url_param_name ] ) );

	/**
	 * Check if the date format is correct (YYYY-MM-DD).
	 *
	 * Example: '2025-03-01' is valid, '03/01/2025' is not.
	 */
	$is_valid_format = preg_match( '/^\d{4}-\d{2}-\d{2}$/', $user_provided_date );

	if ( ! $is_valid_format ) {
		GV_Extension_Calendar_Feed::logger()->error(
			sprintf(
				'Invalid date format in URL parameter "%s". Expected YYYY-MM-DD, got: %s',
				$url_param_name,
				$user_provided_date
			)
		);

		return false;
	}

	/**
	 * Check if the date is actually real.
	 *
	 * Example: '2025-03-01' is real, '2025-13-45' is not (no 13th month or 45th day).
	 */
	list( $year, $month, $day ) = explode( '-', $user_provided_date );

	$is_real_date = checkdate( (int) $month, (int) $day, (int) $year );

	if ( ! $is_real_date ) {
		GV_Extension_Calendar_Feed::logger()->error(
			sprintf(
				'Invalid date in URL parameter "%s": %s (this date does not exist)',
				$url_param_name,
				$user_provided_date
			)
		);

		return false;
	}

	return $user_provided_date;
}

/**
 * Add initialDate to calendar options based on URL parameter.
 *
 * This function checks if a date is provided in the URL and, if valid,
 * sets it as the initial date for the calendar to display.
 *
 * @since TBD
 *
 * @param array $calendar_options The calendar configuration options passed to FullCalendar.
 * @param int   $form_id          The form ID.
 * @param int   $feed_id          The calendar feed ID.
 *
 * @return array Modified calendar options with initialDate if valid URL parameter exists.
 */
function gravitycalendar_add_initial_date_from_url( $calendar_options, $form_id, $feed_id ) {

	$date = gravitycalendar_get_date_from_url();

	if ( false === $date ) {
		return $calendar_options;
	}

	$calendar_options['initialDate'] = $date;

	return $calendar_options;
}

/**
 * Set navigateToEvents to "current" when URL date parameter is present.
 *
 * When a user provides a specific date in the URL, we want the calendar to stay
 * on that date rather than automatically navigating to past or future events.
 * This overrides the "No Current Events Behavior" setting to "Stay on Today".
 *
 * @since TBD
 *
 * @param array $extra_options Extra calendar options (not standard FullCalendar options).
 * @param int   $form_id       The form ID.
 * @param int   $feed_id       The calendar feed ID.
 *
 * @return array Modified extra options with navigateToEvents set to 'current'.
 */
function gravitycalendar_set_navigate_to_current_from_url( $extra_options, $form_id, $feed_id ) {

	$date = gravitycalendar_get_date_from_url();

	if ( false === $date ) {
		return $extra_options;
	}

	/**
	 * URL parameter exists, so set navigateToEvents to 'current'.
	 *
	 * This means "Stay on Today (Show Current Calendar)" and prevents the calendar
	 * from automatically jumping to past or future events when there are no events
	 * in the current view.
	 */
	$extra_options['navigateToEvents'] = 'current';

	return $extra_options;
}
```

```
/**
 * GravityCalendar - URL Parameter Initial Date Support
 *
 * This snippet allows users to pre-select a calendar date via URL parameter.
 *
 * Usage Examples:
 * - ?calendar_date=2025-03-01
 * - ?calendar_date=2025-03-15
 * - ?calendar_date=2025-12-25
 */

/**
 * The URL parameter name to use for the initial date.
 *
 * Example: If set to 'calendar_date', use ?calendar_date=2025-03-01 in the URL
 * Example: If set to 'start_date', use ?start_date=2025-03-01 in the URL
 */
define( 'GRAVITYCALENDAR_DATE_URL_PARAM', 'calendar_date' );

add_filter( 'gravityview/calendar/options', 'gravitycalendar_add_initial_date_from_url', 10, 3 );
add_filter( 'gravityview/calendar/extra_options', 'gravitycalendar_set_navigate_to_current_from_url', 10, 3 );

/**
 * Get and validate date from URL parameter.
 *
 * This helper function extracts the date from the URL, validates the format,
 * and ensures it's a real date. Returns the validated date string or false.
 *
 * @since TBD
 *
 * @return string|false The validated date string (YYYY-MM-DD) or false if invalid/missing.
 */
function gravitycalendar_get_date_from_url() {

	/**
	 * Check if the URL has our date parameter.
	 */
	$url_param_name = GRAVITYCALENDAR_DATE_URL_PARAM;

	// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Reading URL parameter for display only.
	if ( ! isset( $_GET[ $url_param_name ] ) ) {
		return false;
	}

	/**
	 * Get the date from the URL and clean it up for security.
	 */
	// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Reading URL parameter for display only.
	$user_provided_date = sanitize_text_field( wp_unslash( $_GET[ $url_param_name ] ) );

	/**
	 * Check if the date format is correct (YYYY-MM-DD).
	 *
	 * Example: '2025-03-01' is valid, '03/01/2025' is not.
	 */
	$is_valid_format = preg_match( '/^\d{4}-\d{2}-\d{2}$/', $user_provided_date );

	if ( ! $is_valid_format ) {
		GV_Extension_Calendar_Feed::logger()->error(
			sprintf(
				'Invalid date format in URL parameter "%s". Expected YYYY-MM-DD, got: %s',
				$url_param_name,
				$user_provided_date
			)
		);

		return false;
	}

	/**
	 * Check if the date is actually real.
	 *
	 * Example: '2025-03-01' is real, '2025-13-45' is not (no 13th month or 45th day).
	 */
	list( $year, $month, $day ) = explode( '-', $user_provided_date );

	$is_real_date = checkdate( (int) $month, (int) $day, (int) $year );

	if ( ! $is_real_date ) {
		GV_Extension_Calendar_Feed::logger()->error(
			sprintf(
				'Invalid date in URL parameter "%s": %s (this date does not exist)',
				$url_param_name,
				$user_provided_date
			)
		);

		return false;
	}

	return $user_provided_date;
}

/**
 * Add initialDate to calendar options based on URL parameter.
 *
 * This function checks if a date is provided in the URL and, if valid,
 * sets it as the initial date for the calendar to display.
 *
 * @since TBD
 *
 * @param array $calendar_options The calendar configuration options passed to FullCalendar.
 * @param int   $form_id          The form ID.
 * @param int   $feed_id          The calendar feed ID.
 *
 * @return array Modified calendar options with initialDate if valid URL parameter exists.
 */
function gravitycalendar_add_initial_date_from_url( $calendar_options, $form_id, $feed_id ) {

	$date = gravitycalendar_get_date_from_url();

	if ( false === $date ) {
		return $calendar_options;
	}

	$calendar_options['initialDate'] = $date;

	return $calendar_options;
}

/**
 * Set navigateToEvents to "current" when URL date parameter is present.
 *
 * When a user provides a specific date in the URL, we want the calendar to stay
 * on that date rather than automatically navigating to past or future events.
 * This overrides the "No Current Events Behavior" setting to "Stay on Today".
 *
 * @since TBD
 *
 * @param array $extra_options Extra calendar options (not standard FullCalendar options).
 * @param int   $form_id       The form ID.
 * @param int   $feed_id       The calendar feed ID.
 *
 * @return array Modified extra options with navigateToEvents set to 'current'.
 */
function gravitycalendar_set_navigate_to_current_from_url( $extra_options, $form_id, $feed_id ) {

	$date = gravitycalendar_get_date_from_url();

	if ( false === $date ) {
		return $extra_options;
	}

	/**
	 * URL parameter exists, so set navigateToEvents to 'current'.
	 *
	 * This means "Stay on Today (Show Current Calendar)" and prevents the calendar
	 * from automatically jumping to past or future events when there are no events
	 * in the current view.
	 */
	$extra_options['navigateToEvents'] = 'current';

	return $extra_options;
}
```

## Usage

### Basic example

Share this URL with your users:

`https://example.com/calendar-page/?calendar_date=2025-03-15 `

The calendar will automatically display March 15, 2025 when loaded.

### Date format requirements

The date **must** be in ISO 8601 format: `YYYY-MM-DD`

**Valid examples:**

- `?calendar_date=2025-01-01` (January 1, 2025)
- `?calendar_date=2025-12-31` (December 31, 2025)
- `?calendar_date=2026-06-15` (June 15, 2026)

**Invalid examples:**

- `?calendar_date=03/15/2025` (US format - not supported)
- `?calendar_date=15-03-2025` (European format - not supported)
- `?calendar_date=2025-13-45` (Invalid date - no 13th month)

### Multiple calendars on one page

The URL parameter will affect **all calendars** on the page. If you need different behavior for specific calendars, you can modify the snippet to check the `$feed_id` parameter:

```
function gravitycalendar_add_initial_date_from_url( $calendar_options, $form_id, $feed_id ) {
    // Only apply to calendar feeds #5 and #12
    $allowed_feeds = array( 5, 12 );

    if ( ! in_array( $feed_id, $allowed_feeds, true ) ) {
        return $calendar_options;
    }

    // ... rest of the code continues here
}
```

```
function gravitycalendar_add_initial_date_from_url( $calendar_options, $form_id, $feed_id ) {
    // Only apply to calendar feeds #5 and #12
    $allowed_feeds = array( 5, 12 );

    if ( ! in_array( $feed_id, $allowed_feeds, true ) ) {
        return $calendar_options;
    }

    // ... rest of the code continues here
}
```

### Disabling automatic "Stay on Today" behavior

By default, when a URL date parameter is present, the snippet automatically sets the Calendar feed’s **No Current Events Behavior** to "Stay on Today (Show Current Calendar)".

If you want to keep your calendar's configured **No Current Events Behavior** setting, remove this line from the snippet:

```
add_filter( 'gravityview/calendar/extra_options', 'gravitycalendar_set_navigate_to_current_from_url', 10, 3 );
```

```
add_filter( 'gravityview/calendar/extra_options', 'gravitycalendar_set_navigate_to_current_from_url', 10, 3 );
```

And delete the `gravitycalendar_set_navigate_to_current_from_url` function at the bottom of the snippet.

## Customization

### Changing the URL parameter name

By default, the snippet uses `calendar_date` as the URL parameter. To use a different parameter name:

- Open the snippet file or your functions.php
- Find this line near the top:

`define( 'GRAVITYCALENDAR_DATE_URL_PARAM', 'calendar_date' ); `

- Change `'calendar_date'` to your preferred parameter name:
`define( 'GRAVITYCALENDAR_DATE_URL_PARAM', 'start_date' ); `

4. Save the file
5. Your URLs will now use the new parameter:

`https://example.com/events/?start_date=2025-03-15 `

### Common customizations

**Use "date" as the parameter:**

`define( 'GRAVITYCALENDAR_DATE_URL_PARAM', 'date' ); // URL: ?date=2025-03-15`

**Use "event\_date" as the parameter:**

`define( 'GRAVITYCALENDAR_DATE_URL_PARAM', 'event_date' ); // URL: ?event_date=2025-03-15`

## Troubleshooting

### The calendar doesn't navigate to the specified date

**Check these common issues:**

- **Date format:** Make sure you're using `YYYY-MM-DD` format
- **Parameter name:** Verify the URL parameter matches what's defined in `GRAVITYCALENDAR_DATE_URL_PARAM`
- **Snippet activation:** Confirm the snippet is active and saved correctly
- **Browser cache:** Clear your browser cache and try again

### How to view error logs

If dates aren't working, check your error logs:

- [Enable logging in GravityKit](https://www.gravitykit.com/docs/gravityview/advanced/gravityview-logging-tools/)
- Look for entries starting with "Invalid date format" or "Invalid date"
- The log will show exactly what date was received and why it failed validation

## Related resources

- [FullCalendar initialDate option](https://fullcalendar.io/docs/initialDate)