Displaying Stager Event Calendars on Your Site

7 min read
Posted in
  1. Examples and use cases of event calendars
  2. Four ways to display calendars with WP Stager Integration
  3. 1. Using the Stager Event Calendar Gutenberg Block
  4. 2. Using the Stager Event Calendar Elementor Widget
  5. 3. Using shortcodes
  6. wpstager_calendar
  7. wpstager_today
  8. wpstager_ongoing
  9. 4. Using the Calendar PHP Class — for developers
  10. List, cards, calendar, or custom views
  11. “Calendar” view
  12. Calendar filters
  13. Customization options
  14. Advanced Features
  15. Asynchronous Rendering
  16. Custom date ranges
  17. Custom templates
  18. Troubleshooting

This guide explains how to display Stager event calendars on your WordPress site using the WP Stager Integration plugin. You’ll see the different ways to output calendars, how to choose the right time period and layout, and which options you can tweak for your design and content. The guide assumes you’ve already completed the plugin setup, and confirmed that events are syncing correctly.

💡 Looking for an integration partner who does the full integration for you? Every license comes with a Free Configuration Service, and we also offer a paid Full Integration Service!

Examples and use cases of event calendars

Using the WP Stager Integration plugin, you can render a wide variety of Stager event calendars on your site, including:

  • Full event calendars with different layouts
  • An “upcoming events” sections
  • Daily/weekly/monthly/yearly archive-style pages
  • A “Today’s events” section
  • Currently ongoing events
  • Any other custom date ranges and layouts!

Four ways to display calendars with WP Stager Integration

The WP Stager Integration plugin gives you three main ways to display calendars:

  • The Stager Event Calendar Gutenberg block (recommended for most users → no code)
    Used in the WordPress Block Editor.
  • The Stager Event Calendar Elementor widget (for sites that use Elementor as the page builder).
  • Multiple shortcodes (flexible and theme-agnostic → low code)
    Can be inserted in any place where text can be inserted.
  • The Calendar PHP class (for developers building custom templates → custom code)
    For use in theme, plugin or template code files.
The WP Stager Integration plugin offers three ways to display calendars: Blocks, shortcodes and using PHP code.

1. Using the Stager Event Calendar Gutenberg Block

The easiest way to add a calendar is via the block editor:

  • Open the page or post where you want to show a calendar.
  • Click + in the top left corner to add a block.
  • Search for “Stager Event Calendar”.
  • Insert the block and use the sidebar settings to choose:
    • Which time period to show: All events, today’s events, the current week/month/year, currently happening events, etc.
    • Which view to use: A list, cards or actual calendar grid
    • Whether to show navigation, labels, images, etc.
    • And more settings!

The block renders a preview directly in the editor, so you get a good idea of how it will look on the front end.

Using the Stager Event Calendar block is the easiest way to display calendars on your site.

2. Using the Stager Event Calendar Elementor Widget

  • Open the page or post where you want to show a calendar using the Elementor editor (click “edit with Elementor” if the Elementor editor is not opened by default).
  • In the Elementor editor, add a new widget by clicking on the + icon in the content, or in the top menu bar on the left.
  • Search for the “Stager Event Calendar” widget.
  • Insert the widget and use the sidebar settings to choose:
    • Which time period to show: All events, today’s events, the current week/month/year, currently happening events, etc.
    • Which view to use: A list, cards or actual calendar grid
    • Whether to show navigation, labels, images, etc.
    • And more settings!
  • The widget renders a preview directly in the editor, so you get a good idea of how it will look on the front end.

3. Using shortcodes

Shortcodes are ideal if you:

  • Use the “Classic Editor”
  • Use the “Shortcode” block in the block editor
  • Want to place calendars in widget areas, custom fields, page builders (like Elementor, Divi) etc.
  • Need a quick way to drop a calendar into any content.
  • Are editing template parts directly (utilizing do_shortcode() in PHP).

See below an overview of the main shortcodes for calendars and some examples in how to use them.

💡 Refer to our Shortcode documentation for all information about using the shortcodes and all available attributes (settings) per shortcode.

wpstager_calendar

Highly configurable calendar for any date range or layout.

// This will render the current day
[wpstager_calendar scope="day"]

// This will render the calendar for the current week
[wpstager_calendar scope="week"]

// This will render the calendar for the current month with a calendar view
[wpstager_calendar scope="month" view="calendar"]

// This will render the calendar for the current year, with the class "view-my-custom-template" added to the calendar element
[wpstager_calendar scope="year" view="my-custom-template"]

// This will render the calendar for the current week with custom navigation labels, and the week label hidden
[wpstager_calendar scope="week" nav_label_next="Next week" nav_label_previous="Previous week" show_label_week="false"]

wpstager_today

A dynamically updated list of all events taking place on the current day.

// This will render the current day's events
[wpstager_today]

// This will hide the day label
[wpstager_today show_label_day="false"]

// This will show the day label and hide the navigation
[wpstager_today show_label_day="true" show_nav="false"]

wpstager_ongoing

A dynamically updated list of all events that are currently taking place.

// This will render the currently happening events
[wpstager_ongoing]

4. Using the Calendar PHP Class — for developers

If you are building a custom theme or template, you can use the Calendar class to call the calendar rendering methods directly from PHP. This is useful when you want complete control in theme or template files, or if your are building a custom plugin or integration.

💡 Refer to the Calendar class documentation for information about the available rendering methods.

// Render all upcoming events
\WP_Stager_Integration\Calendar::render_all( array(
    'show_past_events' => false,
) );

// Render currently happening events
\WP_Stager_Integration\Calendar::render_currently_happening();

// Render today's events
\WP_Stager_Integration\Calendar::render_day();

// Render the current week, month or year
\WP_Stager_Integration\Calendar::render_week();
\WP_Stager_Integration\Calendar::render_month();
\WP_Stager_Integration\Calendar::render_year();

// Render specific ranges
\WP_Stager_Integration\Calendar::render_week( 12 ); // Week 12, this year
\WP_Stager_Integration\Calendar::render_month( 5 ); // May, this year
\WP_Stager_Integration\Calendar::render_month( 2, 2027 ); // February 2027

// Render the coming three weeks
$start = time();
$end   = strtotime( '+3 weeks' );
\WP_Stager_Integration\Calendar::render_range( $start, $end );

// Fully custom range, with "list" view
$start = strtotime( '2026-04-25 00:00:00' ); // April 4th, 2026 00:00:00
$end   = strtotime( '2026-05-15 23:59:59' ); // May 15th 2026, 2026 23:59:59
\WP_Stager_Integration\Calendar::render_range( $start, $end, array(
    'view' => 'list', // Set 'view' to 'list'
) );

List, cards, calendar, or custom views

Out of the box, calendars can be rendered with either a “list”, “cards”, or a “calendar” view. The list view renders a list of events, the cards view renders events as cards, and the calendar view renders an actual calendar grid with 7 columns for each day of the week.

Examples of different calendar views, including a list view, cards, and a calendar view.

It’s completely possible to render a calendar with a custom views. The $args['view'] argument (or the view attribute when using shortcodes) determines the type of view to render, and is used to add a "view-{$view}" class to the calendar—so you can write custom CSS targeting that view specifically.

Here’s a quick overview of the different styles and appearances of the calendars:

“Cards” view, text below image

The cards view renders events as cards, displaying their image and date/time information — which can be adjusted and/or disabled.

Loading calendar…

“Cards” view, text over image

Text can also be rendered overlayed on top of the image, for a more unified look.

Loading calendar…

“Calendar” view

The calendar view renders a traditional calendar with events appearing inside their respective days. All month, day, and time labels can be adjusted and or disabled.

Loading calendar…

“List” view, without images

The list view renders events in a horizontal list. Whenever the event images are disabled, the list is clear and concise.

Loading calendar…

“List” view, with images

With images enabled, the events are shown as large cards. The day and time labels can be modified and disabled.

Loading calendar…

Calendar filters

All calendars can be displayed with a filter enabled. By default, filters are not shown in calendars, but its very easy to enable them. Please refer to our guide to Calendar Filters for more information and examples on how to use and display filters.

Different filter appearances shown side by side.

Customization options

The calendars allow for customization using its options. The options are available in all rendering methods (Blocks, Elementor widgets, shortcodes, PHP code, etc). Some of the things you can modify include:

  • Enabling/disabling navigation controls and editing button labels
  • Enabling/disabling and editing date labels
  • Enabling/disabling displaying empty periods (days/weeks/months/years) in the calendars
  • Enabling/disabling displaying event images and customizing the layout
  • Whether to include past events in the calendar, or only show upcoming events
  • Customizing the text displayed in periods (days/weeks/months/years) that don’t contain events
  • And more!

Advanced Features

Asynchronous Rendering

For performance, calendars can be rendered asynchronously:

  • The block uses async rendering by default (unless disabled globally).
  • Async mode initially renders a lightweight placeholder, then loads the calendar markup via AJAX.
  • This is useful for pages with multiple calendars or many events.

If async rendering is disabled in the plugin settings, calendars are rendered immediately on the server instead.

💡 For performance and fast load times, it’s almost always better—and therefore recommended—you keep Asynchronous Rendering enabled.

Custom date ranges

For more bespoke layouts, you can target exact date ranges in PHP using render_range(), render_month(), render_week(), etc., and pass the same options you’d use in a shortcode. This allows you to match complex design requirements while still leveraging the plugin’s logic and templates.

Custom templates

The calendar uses template parts located under template-parts/calendar within the plugin folder. Advanced users and theme developers can:

  • Override these templates via a filter hook.
  • Provide completely custom markup for year, month, week, day, and event components.
  • Combine with the view attribute for multiple layouts on the same site.

Troubleshooting

If your events are not syncing to your site, please check the following:

  1. Are the events you want to sync actually published to the publication channel? In Stager, the publication channel checkbox needs to be checked for every event you want to publish: Go to the event you want to publish → Publicity (tab) → Publication (section) → My channels → Check the checkbox next to the publication channel. Then under Publishing my channels, make sure the Publish box is checked. If this value is set to “Schedule to publish on…” it will be published on the date you choose. Save the event if any changes have been made.
  2. Do the events you want to sync have a status that is published to the feed? Any event with the status set to “Option” won’t be published to the feed: Go to the event you want to publish → Main (tab) → Event status → Make sure it is not set to “Option”.
  3. Then, go to your site and request an update through the plugin’s settings → the Synced data sub page (in the sidebar menu) → Sync now. After a few minutes the events should appear on your site.

If you don’t see any events after syncing, make sure to trigger an initial sync from your Stager account, through Stager → Settings → Integrations → Your publication channel → Under the Testing section, next to Initial sync, click Send upcoming events to sync upcoming events, or Send all events to also sync past events. Then after a few minutes, try to sync again from your site through the plugin’s settings → the Synced data sub page (in the sidebar menu) → Sync now.

If it still doesn’t work, click Send upcoming events or Send all events again and wait 30 minutes.

If your site still doesn’t sync the events, please get in touch, and we’ll help you out!

This could be because of a number of reasons:

  • The “Calendar styling” setting might be disabled. Enable it through WP Stager Integration → Settings → Calendar styling.
  • The default calendar view might be configured as “List”. You can manage the default calendar view through WP Stager Integration → Settings → Default calendar view.
  • The method you used to render the calendar (block editor, shortcode, etc) might specify the view as “list”. See the documentation for examples on how to change the calendar’s “view” option.

Please verify that the “Calendar Styling” setting is enabled through WP Stager Integration → Settings → Calendar styling.

This setting exists to allow users as much freedom as they need to style calendars themselves.

You can enable/disable these labels globally through the WP Stager Integration → Settings → Enable day labels / Enable week labels / Enable month labels / Enable year labels.

If your calendar is added as a block in the block editor, you can modify its settings from there.

If you’ve added your calendar as a shortcode, please refer to the Shortcode documentation to see how to edit the calendar appearance using shortcodes.

By default, event pages are disabled. You can enable event pages by adding a “permalink base” for event pages through WP Stager Integration → Settings → Events (tab) → Permalink base. When you enter a value here, event pages become enabled, as well as an additional setting to manage the permalink structure. This way, events in calendars will get a clickable link.

💡 If you ever get stuck or have a question, please check our FAQs, our Free Integration Service, our paid Full Integration Service, or reach out to us!

Get WP Stager Integration

🎁 Limited offer: Use code WELCOME26 to get your first month for free!

Get started