To use these parameters, add them to your shortcode as such:
[ics_calendar url="YOUR_ICAL_FEED_URL" attach="true" color="#ff0000"]
Click any parameter name in the list below for usage details.
To use these parameters, add them to your shortcode as such:
[ics_calendar url="YOUR_ICAL_FEED_URL" attach="true" color="#ff0000"]
Click any parameter name in the list below for usage details.
attach
Use the attach="true"
parameter to display attachments with events. Attachments that are browser-friendly images (e.g. JPEG or PNG) will display directly on the page along with the event’s description. Other attachments will display as a clickable download link.
Images shared from Google Drive will be clickable links, rather than displaying inline, due to the structure of Google Drive links and file access permissions.
If a user who does not have permission to access a particular file on your Google Drive clicks the link, you will receive an automated email from Google requesting permission for that user to access the file. For this reason, you may not want to include attachments in your feed if your site is public.
Google does not provide any way around this limitation, nor a way to make event images/attachments directly publicly accessible.
color
You can apply a color to events in your feed by using the color
parameter. This is especially helpful if you have multiple feeds and you want to use color coding to distinguish the feeds within your calendar. Add hex color values to this parameter and they will be applied to your feeds in the same order as the feeds are entered in the url
parameter. For example, if you have three feeds and you want to color them purple, green and orange, you could use color="#800080 #008000 #ffa500"
. The base color will be used as a left border on each event, and a lighter tint of that color will be used as the background on the events. Use a tool like the HTML Color Picker to select hex values, if necessary. (Note: the color
parameter supports either space- or pipe-delimited lists.)
columnlabels
By default the grid’s column labels will be the full names of the days of the week. For tighter layouts you can add columnlabels="short"
to use 3-letter abbreviations, or columnlabels="min"
to use 1- or 2-letter abbreviations. (The full day names and abbreviations are in the plugin’s translation files for all supported languages.) Applies to month and week views only.
compact
Set compact="true"
to activate a more compact display of whichever view you are currently using. The exact layout changes will vary by view; not all views are affected. It is recommended that you also use toggle="true"
on list view for maximum effect.
Note:This is currently an experimental feature, and we are looking for feedback. In this version, the changes are that all text is reduced slightly in size, and the list view is collapsed into a new layout with the times left-aligned next to the event titles.
count
Number of events to display, e.g. count="5"
. By default, all upcoming events will be displayed. Applies in list view only.
customoptions
If you are writing your own custom code to extend the plugin’s functionality, use customoptions
to create your own configuration options for the shortcode. The value passed in this attribute is automatically converted into an array using the pipe character |
as a delimiter. (Note that if no pipes are present in the value, it will still be converted into an array with one node.)
debug
Use debug="true"
to turn on the debugger. Extended debugging output is available by setting debug="2"
. Only Administrator-level users will see debugging code. When turned on, a panel will appear at the bottom of the screen with a raw dump of the ICS data array, and possibly additional debugging information. When debugging you may also want to set reload="true"
to reload the feed on each page load.
description
Text string to display as a general description of the calendar. Displays above the calendar, just below title
. If omitted, the feed’s description will display (if any). Use "false"
to display no description.
eventdesc
Use the eventdesc="true"
parameter to display event descriptions. Note: In the month view, descriptions will display on hover; in the list view, descriptions will display in full on the page below the event title (and location/organizer, if shown). In the list view, you can choose to display an excerpt of the description by entering the number of words to show, e.g. eventdesc="12"
. Hovering over the shortened description will show the full description in a tooltip. Month view always shows the full description.
eventdl
Add eventdl="true"
to your shortcode to add a clickable download link to each event. This will download a customized .ics
file containing only the selected event for users to add the event to their personal calendars.
extendmultiday
Per the iCalendar specification, the DTEND
value on all-day events is the first free date in the range, i.e. the date after the event finishes. By default, multi-day all-day events are handled this way. If your feed includes multi-day all-day events that should include the date specified by DTEND
, add extendmultiday="true"
to your shortcode.
feedlabel
By default, each calendar in the color key will be labeled using the title provided in that calendar’s feed. You can override the titles by using feedlabel
. Note that because feed labels may need to contain spaces, the values for this parameter are pipe-delimited |
rather than space-delimited. You can provide custom labels for some feeds and use the default titles as labels for others. For example, if you had three feeds and wanted to keep the default title for the second one, you could use feedlabel="Calendar Label 1||Calendar Label 3"
. (Note two pipes together; this is leaving the second delimited value empty.)
format
By default list view will display dates in the U.S. standard day-month-date format (e.g. “Thursday March 14”). To customize the format to your locale, you can use standard PHP date format strings with the format
parameter. For example, to use the day-month format (e.g. “14 March”), use format="j F"
, or for an abbreviated numbered month/day format (e.g. “Thu 3/14”), use format="D n/j"
.
formatmonthyear
In places where the month and year are displayed without the day number (e.g. headers and month selection dropdown menu in month view), the default format is F Y
(e.g. “March 2020”). Use the formatmonthyear
parameter with PHP date format strings to customize the display. Note: This option only supports month and year characters (F, m, M, n, Y, y), plus spaces, hyphens, periods and slashes. All other formatting characters will be stripped from the output.
guid
A “GUID” or “globally unique identifier,” can be used to give your calendar’s container element a unique HTML id
attribute, making it easy to create an “anchor” link to the calendar within a long page. (Note: the shortcode parameter is guid
instead of id
to avoid a conflict with the id
attribute in the Pro version.)
hidealldayindicator
Hides the “ALL DAY” label that appears above all-day events. hidealldayindicator="true"
hiderecurrence
Version 7.0 introduced recurrence frequency messages in the event description block. You can hide these using hiderecurrence="true"
, or you can hide specific frequency types by entering one or more pipe-delimited frequencies to hide, e.g. hiderecurrence="yearly"
or hiderecurrence="yearly|monthly"
.
hidetimes
By default, start times are always displayed, and end times are displayed on hover. To hide all times (for instance, if the times are also in your event description), add the hidetimes="true"
parameter.
legendposition
Determines where to display the legend (list that identifies the different calendar feeds) relative to the calendar. Valid values are "above"
and "below"
. If omitted or an invalid value, will default to above.
legendstyle
Determines how to display the legend. Valid values are "block"
, "inline"
and "none"
. If omitted or an invalid value, will default to block.
limitdays
By default, the plugin limits the displayed date range to the farthest future event in your feed. Use limitdays="NUMBER"
to override the default limit. Replace NUMBER
with your desired number of days. Note: If your calendar has a very large number of events, setting this value above 365 may affect performance.
linebreakfix
Set this to "true"
only if your feed formats event description line breaks in a way that does not conform properly to the iCalendar spec. Has no effect on properly formatted feeds.
linktitles
If the event data contains a URL, the URL can be added to the display as a clickable link in one of two ways. Use the linktitles="true"
parameter to make the event title into a clickable link to that URL. If linktitles
is not used, and eventdesc="true"
is used, then the URL will be displayed as a clickable link after the event description. These links will always open in a new tab/window. If you do not wish to have event URL links appear at all, use nolink="true"
.
location
Use the location="true"
parameter to display event locations (if available). Note: In the month view, locations will display on hover; in the list view, locations will display in full on the page below the event title.
Version 8.10.0 introduced the option to use location="maplinks"
to make event locations automatically convert into a clickable Google Maps link, unless the feed’s LOCATION
field data already contains HTML or a URL. location="true"
is still supported for displaying locations without adding a Google Maps link.
Important:
location="maplinks"
performs a Google Maps search on the exact text of your events’LOCATION
fields. It does not have a way to verify that the value is a real address, so incomplete locations (e.g. conference room names within your office) may yield nonsensical map results.
maskinfo
In some cases, such as for vacation rental availability, you may not want to show any event details, but simply block out days and times. Use maskinfo="MASK"
, replacing MASK
with the text you wish to display in place of the event title. Event details, location and organizer will also be hidden automatically, regardless of any other settings.
method
The method
attribute can be used to force the plugin to only try retrieving the ICS feed via either cURL or fopen. By default, the plugin tries cURL first and then falls back on fopen. In cases where cURL fails, but with a long timeout, you can use method="fopen"
in the shortcode to bypass cURL. This can significantly improve page load times for calendars that experience this issue with cURL receiving an HTTP 500 error from the calendar server. Conversely, if you only want to load the feed via cURL, and not allow the fopen fallback, use method="curl"
in your shortcode.
monthnav
By default, the month view shows a dropdown (select) menu to navigate available months. Add monthnav
with a value of select
, arrows
, both
or compact
(both, inline without header) to change how this is displayed. Applies to month view only.
nolink
Suppresses display of event links. Useful if your calendar feed automatically inserts a default link on all events that you do not wish to display along with the event description.
nomobile
The standard treatment for month and week views on mobile is to stack the display in a list style, because the grid does not work well scaled to the small size of a mobile display. However, if you wish to retain the grid, add nomobile="true"
to your shortcode. Note that you will probably need to add your own custom CSS to make this display usable. Be sure to wrap your CSS in @media screen and (max-width: 782px) { }
and use .ics-calendar.nomobile .ics-calendar-month-grid
in your CSS selectors.
nomonthheaders
Use nomonthheaders="true"
on list or month view to prevent month headers from displaying on the page. (Has no effect on week view since there are no month headers in that view anyway.)
organizer
Use the organizer="true"
parameter to display event organizer (if available). Note: In the month view, organizers will display on hover; in the list view, locations will display in full on the page below the event title (and location, if shown).
pastdays
By default, list and month views do not include past dates (before the first of the current month, in month view) unless startdate
is used to set an arbitrary start date. You can also set a rolling start by using pastdays="NUMBER"
where NUMBER
is replaced with the number of days back you wish to begin. For instance, to show 3 previous months you could enter pastdays="90"
. This option has no effect in week view.
Notes about the
pastdays
attribute:1. You may need to make adjustments to the
limitdays
option when this is used, as it calculates from the first displayed date, not the current date.2. This attribute has no effect on week view.
reverse
If you want to display a list of past events, use reverse="true"
in your shortcode. The list will start from the current date and move backwards from there.
Use in conjunction with pastdays
to set the number of days to include in the display.
Notes:
reverse
is used, pastdays
and limitdays
are automatically set to the same value. If both are set, pastdays
takes precedence.pastdays
and limitdays
are omitted, only events in the current calendar year will be displayed.reverse
option applies only to list view. It has no effect on other views, due to a logical incompatibility with other layouts.reload
This parameter’s functionality has changed as of version 8.5.5.
By default, ICS Calendar caches your parsed feed data for one hour (3600 seconds). Previous versions supported using reload="true"
to tell the plugin not to cache the calendar data at all. This is still supported, but now the reload
parameter supports any integer value, representing the number of seconds the cache should be retained. For instance, to set the cache to four hours instead of one, use reload="14400"
. If this parameter is omitted or set to 0, false, or a negative value, the default 3600-second (1-hour) cache will apply.
showendtimes
By default, start times are always displayed, and end times are displayed on hover. To always display end times (not just on hover), add the showendtimes="true"
parameter.
skip
Add the skip="NUMBER"
parameter in conjunction with the count
parameter in list view to split a calendar across multiple shortcodes within a page (e.g. a multi-column layout). This NUMBER
of events will be skipped in display. Should match the sum of the count
value(s) from previous shortcode(s) on the page for the same feed.
skiprecurrence
Add the skiprecurrence="true"
parameter to skip parsing recurring events. Use of this setting is discouraged in most cases, as it will prevent recurring events from displaying; however it may be useful for improved performance with extremely large calendars, if recurrences are not needed.
solidcolors
Include solidcolors="true"
in your shortcode to make events in color-coded feeds use the designated color as a solid background behind the text, instead of the default lighter “tint” of the designated color.
startdate
By default, the calendar display will start from the current date. To have the calendar start from an arbitrary date (either in the future or the past), use this parameter with the date in an 8-digit "YYYYMMDD"
format.
stickymonths
Add stickymonths="true"
to your shortcode to have the browser’s address bar automatically update with a month code when the user selects a month from the dropdown menu (month view only). Using this URL will open the page with the given month pre-selected.
title
The title
parameter is optional. If omitted, the title provided by the calendar feed will be displayed. Use “false” (e.g. title="false"
) to hide the title altogether.
toggle
This option’s functionality has been modified as of version 8.8.0
By default, when eventdesc="true"
is set, event descriptions display in a floating box when users hover over an event in table-based calendar views. In list view, the descriptions are displayed directly on the page below the event title.
The toggle
option lets you change this behavior. Setting toggle="true"
will make the event descriptions appear inline when the user clicks on an event’s title. Setting toggle="lightbox"
will cause the description to appear in a pop-up “lightbox” when users click the event title. The lightbox option is especially well suited to calendars that tend to have very long event descriptions, as it allows a much larger space for displaying the descriptions.
tz
Version 6 introduces a new way of parsing date/time values from the feed that allows for timezone overrides. By default, the feed will display events with times adjusted for the local timezone configured under Settings > General > Timezone. You can override the site’s timezone for individual feeds by adding the tz="TIMEZONE"
parameter. You must use a valid named timezone value or the setting will be ignored and the site’s local timezone setting will be used. If your calendar is displaying multiple feeds, you can assign each a separate timezone override, as with feed labels or colors, by entering multiple values, pipe-delimited, in the same order as the feeds in the url
parameter, e.g. tz="America/New_York|Europe/London|Pacific/Auckland"
. If you have multiple feeds but all are in the same timezone, you only need to enter the timezone once.
url
The ICS subscription URL for your feed.
It must be a subscription URL, not a URL that displays your calendar in a web view. (Loading the URL directly in your browser’s address bar should download an .ics
file.) Enter multiple URLs, space- or pipe-delimited, to combine multiple feeds into one calendar display.
This is the only required parameter for the shortcode. (Exception: saved calendars in Pro only need the id
parameter.)
view
Determines which layout to use. View options included in the base plugin are "month"
, "week"
and "list"
. Month view is the default, and this parameter can be omitted entirely. See Views for more details about each view.
Additional view options are available in the Pro version. While we generally recommend using the Calendar Builder to manage calendar settings in Pro, all Pro features can also be entered manually in a shortcode. The additional views currently available in Pro are: "grid"
, "month-with-sidebar"
, "widget"
, "year-availability"
and "year-with-sidebar"
whitetext
Include whitetext="true"
in your shortcode to force all text within the calendar to be white. Useful on pages with dark backgrounds.