gCalFlow: jQuery Google Calendar Event List Plug-in

Show your event list on any website

View the Project on GitHub sugi/jquery-gcal-flow

jQuery Google Calendar Flow plug-in provides a widget to show list of upcoming or recently updated events of public google calendar with configurable options and fully customizable HTML design template.

In the simplest way, you need to specify just calendar ID. The sample on this page is shown by following code:

<div id="gcf-simple"></div>
<script type="text/javascript">
$(function() { $('#gcf-simple').gCalFlow({
  calid: 'linuxfoundation.org_34363837313836302d343036@resource.calendar.google.com'

Google Calendar API v3 Migration Note

Old version of this plugin (< 3.0.0) uses Calendar API v2, and the API has been shutdown at 2014-11-17. Old version is not worked anymore.

Please update to 3.0.0 above for v3 API transition, and check about API key.


jQuery Google Calendar Flow plug-in is highly configurable with CSS, Javascript option and HTML templating!

CSS classes

This plug-in in uses following classes in default template. You can write CSS to override with your design.

If you need more complex change, use template.

  + .gcf-header-block
  | + .gcf-title-block
  |   + .gcf-title
  + .gcf-item-container-block
  | + .gcf-item-block
  |   + .gcf-item-header-block
  |   | + .gcf-item-date-block
  |   | | + .gcf-item-daterange
  |   | + .gcf-item-title-block
  |   |   + .gcf-item-title
  |   + .gcf-item-body-block
  |     + .gcf-item-description
  |     + .gcf-item-location
  + .gcf-last-update-block
    + .gcf-last-update


Following options are available for jQuery#gCalFlow call.

Name Type Default Note
calid string (none) Google Calendar ID (required if data_url is missing)
apikey string (Demo API key) API key (recommended, please read description)
mode string 'upcoming' 'upcoming' for upcoming events, or 'updates' for events ordered by last modified.
data_url string (none) Any jsonp data URL compatible with google's. If this option is specified, 'calid' and 'mode' are ignored.
maxitem int 15 Limit for max number of events. You can set any number, but Google may ignore large numbers.
date_formatter function ISO style formatter This function will be called with two arguments: Date instance and "all day flag".
daterange_formatter function ISO style formatter This function will be called with three arguments: start date, end date and "all day flag".
auto_scroll boolean true
scroll_interval int 10 * 1000 in milliseconds
link_title boolean true Enable link on calendar title
link_item_title boolean true Enable link on item title
link_item_description boolean false Enable link on item description
link_item_location boolean false Enable link on item location with GoogleMap
link_target string '_blank' Target attribute of auto-generated links
item_description_as_html boolean false Set true to treat item descriptions as HTML.
no_items_html string '' Any HTML string for notification when calendar has no events.
callback function null callback function when finish rendering. In this function, a jQuery object contains target node is assigned to 'this'. This is useful to chain other jQuery method or plug-in (e.g. callback: function() { this.effect("highlight") })
globalize_culture string (auto-detect) Culture string for Globalize
globalize_fmt_datetime string 'f' Format string of Globalize for date and time
globalize_fmt_date string 'D' Format string of Globalize for date
globalize_fmt_time string 't' Format string of Globalize for time
globalize_fmt_monthday string 'M' Format string of Globalize for month and day

Use your own API key for v3 API

gCalFlow plugin now uses Google Calendar API v3. All client accesses via v3 API has been checked for quota limit of each API project. v2 has no limitation, but v3 has.

This plugin has been distributed with a API key for demo or really tiny use. If you do not specify apikey option, built-in key will be used. In this case, the widget may fail to be rendered by quota.

I recommend you to create your own API key and use it for stable functionality on your site.

To create API key, visit Google Developers Console. Then, follow bellow;

  1. Create new project (or use project you created before).
  2. Check "APIs & auth" -> "Credentials" on side menu.
  3. Hit "Create new Key" button on "Public API access" section.
  4. Choose "Browser key" and keep blank on referer limitation.

Finally, set your API key on apikey option for gCalFlow() call like following;

<div id="gcf-simple"></div>
<script type="text/javascript">
$(function() { $('#gcf-simple').gCalFlow({
  calid: 'your-calendar-id@calendar.goo...',
  apikey: 'Your-API-key-string-like-AIzaSyD0vtTU...'


If the target element has any child nodes, it will be treated as a custom template. Google Calendar Flow plug-in will replace the contents of elements based on their class name. You can use any design by creating your own template.

Note: To use the default template, keep the target element empty (no child nodes)!

Built-in template

Here is the built-in default. It's a good starting point for creating a modified template.

<div class="gcf-header-block">
  <div class="gcf-title-block">
    <span class="gcf-title"></span>
<div class="gcf-item-container-block">
  <div class="gcf-item-block">
    <div class="gcf-item-header-block">
      <div class="gcf-item-date-block">
        [<span class="gcf-item-daterange"></span>]
      <div class="gcf-item-title-block">
        <strong class="gcf-item-title"></strong>
    <div class="gcf-item-body-block">
      <div class="gcf-item-description">
      <div class="gcf-item-location">
<div class="gcf-last-update-block">
  LastUpdate: <span class="gcf-last-update"></span>
Variable classes

The content of elements with following class name will be replaced:

Class name Change text to... Note
gcf-title Calendar title
gcf-last-update Last update of the calendar
gcf-link (text is not replaced) This class will be set "href" attribute to calendar URL (not used in default).
gcf-item-container-block This class item container. The content of this node is cleared, then gcf-item-block element will be appended for each event item. If template dose NOT have this element, no items will be shown.
gcf-item-block This class will be treated as item template.
gcf-item-daterange Item date range Must be a descendant of gcf-item-block. Formatted by 'daterange_formatter' option.
gcf-item-title Item title Must be a descendant of gcf-item-block.
gcf-item-description Item description text Must be a descendant of gcf-item-block.
gcf-item-location Item location text Must be a descendant of gcf-item-block.
gcf-item-link (text is not replaced) Must be a descendant of gcf-item-block. This class will be set "href" attribute to item URL (not used in default).
gcf-item-date, gcf-item-start-date Item start date Must be a descendant of gcf-item-block (not used in default).
gcf-item-end-date Item end date Must be a descendant of gcf-item-block (not used in default).
gcf-item-update-date Item update date Must be a descendant of gcf-item-block (not used in default).

Date formatting with Globalize 0.x

In default, widget shows ISO style date. To customize date format easily, you can use Globalize 0.x Javascript library (Note: version 1.x alpha is not supported yet! Please use 0.x). By just loading Globalize, default date formatting will be changed to new one which includes full month and weekday names. Load Globalize Javascript files like following;

<script src="/path/to/your/globalize.js" type="text/javascript"></script>
<script src="/path/to/your/cultures/globalize.culture.en-US.js" type="text/javascript"></script>

If you'd like to customize more, tune globalize_fmt_* options (globalize_fmt_datetime, globalize_fmt_date, globalize_fmt_time, globalize_fmt_monthday) with their format string. For example, to use short month/week names and 24h format;

  globalize_fmt_datetime: "dddd', 'MMM' 'dd', 'yyyy' 'HH':'mm",
  globalize_fmt_date: "dddd', 'MMM' 'dd",
  globalize_fmt_time: "HH':'mm",
  globalize_fmt_monthday: "MMM' 'dd"


Title only updates list (template + js options)

Rendered Result:

Ticker (template + js + CSS)

Rendered Result:


MIT License


Tatsuki Sugiura