0 items
Sign in
Buy

Docs

Pre-selecting a calendar date using URL parameters

Estimated reading: 10 minutes

Updated on April 23, 2026

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 #

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 #

  1. Copy the snippet
  2. Add it to your site
/**
 * 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
}

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 );

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:

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

define( 'GRAVITYCALENDAR_DATE_URL_PARAM', 'calendar_date' );  

  1. Change 'calendar_date'   to your preferred parameter name:

define( 'GRAVITYCALENDAR_DATE_URL_PARAM', 'start_date' );  

  1. Save the file
  2. 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:

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

How to view error logs

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

  1. Enable logging in GravityKit
  2. Look for entries starting with “Invalid date format” or “Invalid date”
  3. The log will show exactly what date was received and why it failed validation

Related resources #

Was this page helpful?

Table Of Contents