Google Calendar Events

This is a WordPress plugin, which parses Google Calendar feeds and displays the events as a calendar grid or list on a page, post or widget. Events from multiple feeds can be displayed on one grid or list. You can specify how many events to retrieve, whether to retrieve past events and how long to cache the feed for, amongst other things. Grids can have AJAX functionality, which allows you to change the month, if required.

The calendar grid markup is generated using a modified version of the PHP Calendar script (2.3) by Keith Devens. As of version 0.2, tooltips are created using the jQuery tooltip plugin, qTip.

Don’t hesitate to let me know if you have any questions, problems, feedback etc. Leave a comment at the bottom of the page or contact me.

Jump to:


Visit the demo page to see what the plugin can do.


The current version is 0.7.2

You can download Google Calendar Events from the WordPress plugin directory page.


Either use the automatic installer from within your WordPress admin, or follow the below steps:

  • Download from the plugin repository
  • Extract the file
  • Copy the google-calendar-events directory to your WordPress plugins directory (probably wp-content/plugins)
  • Login to your WordPress admin, navigate to the Plugins section and activate Google Calendar Events
  • You should now see a new Google Calendar Events settings page under the Settings tab

Adding a Feed

Go to the Google Calendar Events settings page and click the Add Feed button. Here’s an explanation of the various fields:

  • Feed ID
    This is automatically assigned, it’s just a unique identifier.
  • Feed Title
    This can be whatever you like. Try to use something descriptive so that it will be easy to remember which feed is which (e.g. ‘Upcoming Club Events’ rather than ‘Feed 1′).
  • Feed URL
    This is the URLto the Google Calendar feed. It should be something like this: end of the URL may have /basic or /fullon the end, both should work ok.If you are using your own feed, you can find the URL by logging into Google Calendar then clicking on the calendar settings. In the Calendar Address section you should see an orange XML button, click on it to see your feed URL. Copy and paste the URL into the Feed URL field.
  • Retrieve events from
    The time at which to start retrieving events. Select one of the options from the drop-down box, and then specify an additional offset for the start time / date you require. The offset should be given in seconds (3600 seconds = 1 hour, 86400 seconds = 1 day), and can be negative.If you are using the ‘Specific date / time’ option, enter the UNIX timestamp for the date / time into the textbox. You can generate UNIX timestamps here.Take a look at this post for a few examples of how to use this option.
  • Retrieve events until
    The time at which to stop retrieving events.The instructions for the ‘Retrieve events from’ option (above) also apply here.
  • Maximum number of events to retrieve
    The maximum number of events to retrieve from the calendar feed. Due to caching and timezone issues, it is a good idea to set this to a higher number than you actually want to display. 5 to 10 higher should be fine in most cases. You can specify the exact number to display in the widget options or shortcode parameters.
  • Date format
    A PHP date format string. Leave this empty to just use the default for your blog (in Settings > General). Stick to just day / week / year formatting here, leave hours / minutes / seconds for the time format (below).
  • Time format
    A PHP date format string. Leave this empty to just use the default for your blog (in Settings > General).
  • Timezone adjustment
    If you are having problems with dates and times being shown incorrectly for your timezone, select your required timezone from the drop-down box.
  • Cache duration
    This is the length of time to keep the feed cached, in seconds (43200 seconds = 12 hours). You might want to reduce this value if your calendar updates very often but avoid setting it really low or page load times and calls to Google’s servers will be increased. If you want to update the feed cache ‘right now’ to check any events you have added to your Google Calendar, set this to 0, then refresh any page with the calendar on it. You should then set this back to a higher number.
  • Show multiple day events on each day?
    If checked, events that span multiple days will be shown on each day that they span. If unchecked, multi-day events will only be shown on their first day.

Display options

To control the information that is displayed for each event in the grid tooltip or list, you can use either the simple display options, or the event display builder. The event display builder is much more flexible than the simple display options.

The simple display options are described below. There is a separate, in-depth guide to the event display builder.

Simple Display Options

  • Display start time / date?
    Select how to display the start time and date for events from the drop-down box. You can also enter some text to be displayed before the start time / date in the textbox
  • Display end time / date?
    Same applies here.
  • Separator text / characters
    If you have chosen to display the time and date for either of the above two settings, you can specify the text / characters to separate the time and date here (include spaces).
  • Display location?
    If checked, the location of events will be displayed (if a location was set when the event was created). You can also enter some text to be displayed before the location in the textbox.
  • Display description?
    Same as the location, but you can also specify a maximum word count for the description text. This can prevent the tooltips / lists becoming very long if your events have lengthy descriptions.
  • Display link to event?
    If checked, a link will be displayed for each event, which links to the Google Calendar page for that event. You can also specify whether these links will open in a new window, and the link text to be displayed.

When you’re done, click the Add Feed button. You will be redirected back to the main plugin settings page and you should see your feed listed in the current feeds section.

Please note that Google Calendar feeds that you add should have public sharing enabled and have the ‘Share only my free/busy information (Hide details)’ checkbox unchecked (These settings are under ‘Share this Calendar’ in the Settings of your Google Calendar admin).

Event Display Builder Guide

The event display builder requires quite a lot of documentation, so has a page to itself! Please take a look at the event display builder guide.

Editing / Deleting Feeds

On the main plugin settings page, you should see Edit and Delete links for each feed you have added.

The Edit Feed screen is very similar to the Add Feed screen so should be fairly self explanatory by now.

On the Delete Feed screen, check that the feed displayed is the one you wish to delete, then click the Delete Feed button. Make sure that you remove or adjust any widgets or shortcodes etc. that used the feed you have just deleted or you may get errors.

Adding a Widget

You need to have added a feed before you can add a widget, see above for how to do that if you’re not sure. Also, your theme must be widget enabled. If it isn’t, try using one of the other methods explained below.

Once you have added a feed, go to the Widgets page of your WordPress admin (under Appearance) and do the following:

  • Drag the Google Calendar Events widget from the Available Widgets box into one of the widget areas on the right of the screen.
  • Click on the arrow on the right of the widget, you should see some options.
  • Enter the feeds IDs of the feeds you want to display in this widget as a comma separated list (e.g. 1, 2, 4). If you want to display all the feeds you have added, leave this blank.
  • Choose how to display the events from the drop-down-box.
  • Enter the number of events that you want to display in this widget (you can’t display more than the number you specified in the ‘Maximum number of events to display’ option in the feed settings). Enter 0 to display all events that were retrieved.
  • Choose whether you want events to be displayed in ascending or descending order. This only applies to lists.
  • If you want to display a title on the top of the tooltip / each list item, tick the checkbox and enter your desired title text in the text field (can be empty).
  • Click the Save button.

Adding to a Post or Page

To add a calendar grid or list to a post of page, you can use the following shortcode:


It takes up to four different parameters:

  • id – The IDs of the feeds you want to display as a comma separated list (all feeds will be displayed if this is omitted).
  • type – Should be one of the following (defaults to gridif parameter is omitted):
    • list – Events displayed in a list
    • list-grouped – Events displayed in a list, grouped by date
    • grid – Events displayed in a calendar grid for the current month
    • ajax – Events displayed in a calendar grid, with the ability to change months via AJAX
  • title – Title text to be displayed on the top of the tooltip / list items (no title is shown if parameter is omitted).
  • max – The maximum number of events to display (again, you can’t display more than the number you specified in the ‘Maximum number of events to display’ option in the feed settings). All events retrieved will be displayed if set to 0, or if this parameter is omitted.
  • order – The order of events. This only applies to lists. Should be asc or desc (defaults to asc if this parameter is omitted).

So, for example, to display 10 events from feeds 1 and 3 in a AJAX enabled calendar grid with the tooltip title ‘Events on’, use the following:

[google-calendar-events id="1, 3" type="ajax" title="Events on" max="10"]

You can also use the do_shortcode() function to add a grid or list anywhere in a theme / template, like this:

<?php echo do_shortcode( '[google-calendar-events id="1, 3" type="ajax" title="Events on" max="10"]' ); ?>

General Options

These are the options on the main plugin screen.

  • Custom stylesheet URL
    If you want to make changes to the default CSS styles, create a new stylesheet on your server (not in the google-calendar-events directory) and enter its URL into this textbox. The default stylesheet will be overwritten each time the plugin updates, so beware of editing it directly, you will lose your changes.
  • Add JavaScript to footer?
    If the AJAX functionality, or the tooltips don’t appear to work for your site, try ticking this checbox.
  • Loading text
    Enter the text to display when the calendar is loading during an AJAX request.
  • Error message
    Enter an error message to display to non-admin users if events cannot be displayed for any reason. Logged-in admin users will see different error messages indicating the cause of the error.
  • Optimise event retrieval?
    If enabled, the plugin will use an experimental parameter of the Google Data API, called fields. This feature can improve performance significantly as it allows the plugin to request only the information it requires. This means that there is less feed data to transfer and process. It is highly recommended that you leave this option enabled, however, as this is an experimental feature, Google could potentially remove or change it at any time.
  • Use old styles?
    In version 0.7, some changes were made to the default CSS stylesheet. Enabling this option will add another stylesheet that includes much of the stuff that was removed / changed. You should consider updating your custom stylesheet so that you don’t need this enabled. This option will be removed in a future version.

Notes for Google Apps Calendar Users

If you are using a feed from a Google Apps Calendar and are having issues getting things up and running, please take a look at the notes for Google Apps Calendar Users.

AJAX grids

A few things to remember about AJAX grids. This applies to both widgets and full page grids.

  • To have the ability to change month on a grid, you must use the AJAX versions of the grids. See the above sections for how to do this.
  • To change the month, click on the arrows that appear on either side of the grid title.
  • The arrows will only appear if there are more events to show in that direction. For example, if the grid is showing July and there are no events in August or beyond then the next month arrow will not show.
  • Each time you click on one of the arrows, the information is requested from the server, so will take a small amount of time to appear (generally a couple of seconds).

Frequently Asked Questions

For answers to commonly asked questions, please visit the FAQ page.

If the FAQ don’t help, please ask in the comments below, or send me an email.

Things to Note

  • The calendar grid uses the WordPress ‘Week starts on’ setting to determine on which day the grid will start. You can change this in Settings > General.
  • Only a very basic CSS stylesheet is included. The intention is that you will adjust the stylesheet to fit your theme.
  • Styles and JavaScript are added by wp_head() or wp_footer() (if the relevant option is enabled) so ensure that you theme uses these functions or you will need to add the CSS and JavaScript files manually.
  • The plugin is still very much under development so there may be rough edges. I would appreciate any feedback, including bug reports and requests for additional features. Leave a comment below or contact me. Thanks!

To Do

Things I hope to implement / improve at some point:

  • Allow event information to be displayed within calendar grid cells (not just in the tooltip)
  • Different groupings for the grouped list (week, month, year etc)
  • Better handling of feeds that contain only free / busy information
  • Only load JavaScript when needed on the page
  • Allow a month other than “this” month to be displayed initially for calendar grids (first month that has events?)
  • Convert feeds to a custom post type

Any other suggestions?


Several people have asked about making a donation to the continued development and support of the plugin, so I’ve finally got around to sorting it out! Any donations will go towards website hosting costs and stuff like that.

Donations are much appreciated, but please do not feel in any way obligated to donate! I develop and support the plugin because I enjoy doing so, not for any financial gain.

3,885 Responses

  1. Hey, I am using your plugin to replace the ugly and uncustomizable default google calendar embed. However, that calendar has a subscribe button at the bottom that I can’t seem to figure out how to duplicate on my own. Any way to add the subscribe functionality to your plug-in so it can fully replace Google’s native option? Thanks.

  2. Two questions:
    1. Is there a way to link the google calendar to the widget without having to make the google calendar public? I don’t want anyone who clicks on the event to have the ability to mess with the google calendar

    2. Is there any way to have the names of the events come up in the calendar grid itself instead of having to hover the mouse over it?


  3. Hi,

    I’m using your plugin in spanish web site.

    Where can I change this message? When no activity is scheduled

    “There are currently no events to display”

    Thanks for your support


  4. Help with google calendar type = list I need to separate the date by day, month and year, separated by or to apply different style. For example Day Month Year

  5. I have a Google calendar with many many events (at least one per day) but most are not showing. I have refreshed the feed and set the shortcode to display 20000 events. have there been any google API changes or are you aware of any issues that might cause the limiting of events?

    1. Oops… Changing “Retrieve Events From” to “The Beginning of Time” gave me back the Month Backward button. I have “Retrieve Events Until” set to “The End of Time” and still no forward button. Plenty of events on that calendar all the way through May of 2015. Thanks for any input, Ross.

  6. Hi Ross

    I’m having the same problem as Barry reported on 8 July 14: no back and forward arrows for the calendar grid. I really like everything else about this but the no arrows thing is a real problem. I’m using version 0.7.2 of the plugin on WordPress 3.5.2.

    Any suggestions on how to enable this would be really appreciated

  7. Ross,

    Thanks for the plugin. Also using it to replace the out-of-date WordPress Google Calendar plugin, which, among other things, loads an old jQuery version that breaks newer plugins…

    Question: using the widget – list grouped by date – it would be nice if the list could be set up with a tooltip similar to those in the calendar grid displays. Instead of linking out to the google calendar information page, a mouseover or click would bring up the Event Display Builder details.

    Is this something you’ve considered?

  8. Hi Ross – wanted to first thank you for taking the time to develop this plugin, I’ve been looking to develop something like this and this saved me a lot of time!

    I wanted to check with you to see if there is a possibility to query the past X number of events, instead of by days/time? I’ve been looking into the code and was wondering if this is even possible and if it is, is there a syntax that you know of to query this.

    So for example, lets say instead of looking up from Today to End of the week, you would want to look up the next 5 events, regardless of date.

    I’m developing a baseball team site, and would like to show the past 5 games and next 5 games, or something to that extent.

    Hope that makes sense,

    Thank you!

    1. just wanted to note, currently creating a feed with the query parameter


      and setting the start and end time to a large time span will pick up the next 5 events, but am stuck on pulling the previous 5.

      and i would like to try to not have to combine 2 different feeds. I’ve been looking in the API guide and am not seeing anything about previous events.


  9. Is there a way to force the plugin to display the next five days, even if there are no events on a given day?

    Sort of like an agenda view, but empty days are OK.

  10. This is an awesome plug in! How do I set it up to get events from “today”

    Then set up to get from “tomorrow” then the next day…

    In other words- I will set up three feeds, but configure them as the above.

    I can’t seem to get it to feed correctly. Either no dates are available, or it is pulls from two different days. Thanks

  11. Hi,
    Awesome work on the plugin. I was wondering, is there a way to control the width and height of the generated grid calender when inserting the calender using a shortcode .

  12. Hey,

    Love the plugin. I’m having some trouble getting the limit function to work correctly on my description.

    Here’s what I’m doing:
    [if-description limit="7"]Description: [description][/if-description]

    What am I missing?


  13. Hello,

    Is there a way to link an event to another page on the website, rather than to the Google calendar itself?

    Thank you.

  14. Hi Ross, how are you?

    Nice Plugin! I am going to give it a try to see how it works. Also I would like to ask you something to see if I can make it happen and work in some way.

    1) Is there a way to show a Button under the Calendar to add a new event in the Calendar?
    2) Is there a way to make it like a in a FancyBox or a Pop up Window or something like that?

    I am really interesting to implement your plugin because Google Calendar makes what I need, a simple Calendar that shows what I need and send me reminded notifications when before Events. So if I can make it happen or at least see how can I be close to make those 2 point would be fantastic.

    Thank you very much!

  15. Hi, I am trying to add a feature of a calendar on my main page that is sync’d up with a google calendar. I’ve read the instructions of how to install, but i can’t seem to find the “plug-ins” page on the admin page. What is the URL? Thank you

  16. Thanks for this wonderful and powerful plugin. I’ve used this on a number of websites, with only a rare problem, but today I have a problem:

    The calendar shows the next month, September, but not any further. It’s set to use Ajax, I’ve refreshed the feeds, the events are DEFINITELY there on the Google calendar, I’ve set it to pick up 200 events (which should be enough for 8+ months), from the beginning to the end of time.

    What am I missing?

  17. Hi I don’t see Google Calendar Events in the plug ins library in WP

    so i downloaded it from from the WordPress plugin directory page, as directed version

    When I download the current version it does not come in a zip format

    when I select files that I downloaded to upload in WP the uploader will only select one file at a time

    every installation returns errors

    im in the third day of trying to install a stupid calendar on my wp site

  18. Hi Ross,

    Nice plugin and love the options!

    I have 2 questions:
    1. I would like to translate ‘Begins:’, ‘Ends:’, ‘Locations:’ and ‘Description:’. I translated them in the .php file, but that doesn’t seem to work. How can I get these in Dutch?
    2. Can I somehow order (or filter) events from a certain feed by title?

    Thanks and regards,

  19. There are 3 major parts that a company is essential to hqve so its gross sales reps have a authentic likelihood in the greatly aggressive
    subject off Multi level marketing, as well as the competing actively playing area that company’s merchandise competes in:.
    ” Do – Terra’s founders wanted to set a new standard on Therapeutic Grade Essential Oils. Nonetheless vapor purification is the most typical form of removal.


Leave a Reply