=== The Events Calendar Shortcode & Block ===
Contributors: brianhogg
Donate link: https://eventcalendarnewsletter.com/the-events-calendar-shortcode/
Tags: shortcode, event, the events calendar, events, calendar
Requires at least: 6.3
Requires PHP: 7.4
Tested up to: 7.0
Stable tag: 4.0.0
License: GPL2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Add shortcode, block and Elementor widget functionality to The Events Calendar Plugin, so you can easily list and promote your events anywhere.

== Description ==

**Get your events displayed in a customizable list wherever you need them, with The Events Calendar Shortcode & Block!** This plugin fully integrates with The Events Calendar Plugin (free version) by StellarWP, formerly Modern Tribe.

This plugin adds a shortcode, a WordPress block (Gutenberg editor), and now an **Elementor widget** and a **Bricks element** for use with The Events Calendar WordPress Plugin.

Display a list of your events by either adding a block in the new editor, or adding a shortcode to any post, page, or widget.

Here's a quick video showing you what you can do:

[youtube https://www.youtube.com/watch?v=_hpfuoa6MZM]

<blockquote>
If you need extra design and functionality, <a href="https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme&utm_content=description">Get The Events Calendar Shortcode & Block Pro</a>! The Pro version offers seven designs, additional filtering options, and full control over how your events display.

You get the same full integration with The Events Calendar, plus premium support, show multiple shortcodes on one page, a filter bar so users can find what events they want to see, and it works with any WordPress theme.

<a href="https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme&utm_content=description">Check out the Pro version today</a>
</blockquote>

Trusted by 20,000+ WordPress sites and a 4.7 star rating on WordPress.org, The Events Calendar Shortcode & Block is the solution you've been after :)

== How to use The Events Calendar Shortcode & Block ==

You can use the shortcode or block to add a list of your events, filtered by various options. Here's an example of how you'd show the next 8 events in the category festival:

`[ecs-list-events cat="festival" limit="8"]`

With the WordPress block editor, just add a block and search for The Events Calendar Shortcode.

When editing a post or page with Elementor, you can add The Events Calendar Shortcode widget (under "General") and customize the display options.

You can also filter the events in the shortcode and choose from the following options:

* Category: show events from specific categories.
* Number of events: choose the number of events to show.
* Event order: Order in which your events are shown (latest first or last).
* Event dates: Show or hide the date.
* Event venue: Show or hide the venue.
* Event excerpt: Show or hide the event excerpt, and set an excerpt length.
* Event content details: Change the order the event details are displayed.
* Thumbnail: Show or hide a thumbnail image.
* View all events link: Choose whether to include a "view all events" link or not.
* Events from a specific month: show only events from specific months (including current or next month).
* Previous events: Show previous events.
* Hide started events: Hide events when their start time passes.

This gives you full control over how your events are displayed, and is perfect for non-profits, charities, businesses, conferences, and anyone with a WordPress website showing events.

You'll find a full list of how to use these options in the shortcode below in the plugin's FAQs or <a href="https://eventcalendarnewsletter.com/events-calendar-shortcode-pro-options/?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme&utm_content=description">on our documentation page</a>.

<blockquote>
<h3>With Pro, choose your design and get even more control</h3>

<a href="https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme&utm_content=description">The Events Calendar Shortcode & Block Pro</a> adds extra designs, including a true calendar view, compact and column-based designs, and advanced features like events grouped by day.

Plus, get advanced control over how your events display:

<ul>
<li><strong>Events in the next week:</strong> Show events happening in the next X days, for example tomorrow, next week, or next month.</li>
<li><strong>Only specific days:</strong> Show only events on specific days.</li>
<li><strong>Display events by location:</strong> Choose to show events by city, state, or country!</li>
<li><strong>Only featured events:</strong> Show only events you mark as featured.</li>
<li><strong>Full event description:</strong> Show the full event description, instead of just a short excerpt.</li>
<li><strong>Only show start time:</strong> Just show the start time of your event.</li>
<li><strong>Hide recurring events:</strong> Only show the first instance of a recurring event.</li>
<li><strong>Filter bar:</strong> Allow visitors to choose what events they want to see.</li>
<li><strong>Pagination:</strong> Let visitors view additional pages of events.</li>
<li><strong>Custom design:</strong> Create your own using Shortcode Variables or templates, or use one of the seven built-in options.</li>
<li><strong>Plus much more:</strong> <a href="https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme&utm_content=description">check out The Events Calendar Shortcode & Block Pro details here</a>.</li>
</ul>

<a href="https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme&utm_content=description">The Events Calendar Shortcode & Block Pro</a> is ideal for non-profits, charities, businesses, conferences, developers, and WordPress agencies who need the extra control and support straight from the plugin developer. <a href="https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme&utm_content=description">Check it out here</a>.
</blockquote>

== Who's using The Events Calendar Shortcode? ==

**William Penn University** is a private liberal arts university located in Oskaloosa, Iowa. The university offers more than 20 majors through seven academic divisions, with a focus on leadership, technology, and inspired potential. As an institution that hosts various events throughout the year, William Penn University needed an efficient way to display and manage its event calendar on its website. The university chose to implement The Events Calendar Shortcode plugin to streamline event management and improve the overall user experience.

The university decided to use The Events Calendar Shortcode plugin, which integrates seamlessly with The Events Calendar WordPress Plugin. The plugin allows the university to display a list of events using a shortcode or a WordPress block. This makes it easy for technical and non-technical users to add events to the website without any coding knowledge.

**365Austin** is a popular website that curates and shares the best events, activities, and experiences in Austin, Texas. With a comprehensive event calendar, the platform aims to make it easier for locals and tourists alike to discover and participate in exciting events happening in the city. To improve event management and user experience, 365Austin chose to implement The Events Calendar Shortcode plugin on its website.

**CREST** (Center for Research in Economics and Statistics) is a renowned research center that brings together researchers from various fields, including economics, finance, sociology, and statistics. To facilitate collaboration and knowledge sharing among its members and the wider academic community, CREST hosts various seminars, workshops, and conferences. A comprehensive event calendar on the CREST website plays a crucial role in keeping researchers informed and engaged.

Each event listing includes essential information such as the title, date, time, speaker, and a brief description of the topic. The calendar is designed to be user-friendly and easily accessible, allowing researchers to stay informed about upcoming events relevant to their fields of interest.

== Documentation ==

The full list of options you can use can be found <a href="https://eventcalendarnewsletter.com/events-calendar-shortcode-pro-options/?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme&utm_content=description">on our documentation page</a>.

We also have a full course on setting up The Events Calendar, our The Events Calendar Shortcode & Block plugin, and more: <a href="https://eventcalendarnewsletter.com/the-events-calendar-course/?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme&utm_content=description">Getting Started Promoting Events with The Events Calendar plugin for WordPress</a>

If you have any other questions about the plugin, you can post a thread <a href="https://wordpress.org/support/plugin/the-events-calendar-shortcode/">in the WordPress.org forum</a>. If you're looking for premium, personalized support, consider upgrading to <a href="https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme&utm_content=description">The Events Calendar Shortcode & Block Pro</a>.

Still have a question? You can send us an email at info@eventcalendarnewsletter.com.

This plugin is not developed by or affiliated with The Events Calendar WordPress plugin, StellarWP or Modern Tribe in any way.

== Installation ==

1. Install The Events Calendar Shortcode Plugin from the WordPress.org repository or by uploading the-events-calendar-shortcode folder to the /wp-content/plugins directory. You must also install The Event Calendar Plugin by Modern Tribe and add your events to the calendar.

2. Activate the plugin through the Plugins menu in WordPress

3. If you don't already have The Events Calendar (the calendar you add your events to) you will be prompted to install it

You can then add The Events Calendar Block or `[ecs-list-events]` shortcode to the page or post you want to list events on.  [Full list of options available in the documentation](https://eventcalendarnewsletter.com/events-calendar-shortcode-pro-options/?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme-install-docs&utm_content=description).

== Frequently Asked Questions ==

= What are the shortcode and block options for customizing my events? =

Here's the [full list of shortcode and block options](https://eventcalendarnewsletter.com/events-calendar-shortcode-pro-options/?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme-faq-options&utm_content=description) you can use to customize how your events display:

* Basic shortcode: `[ecs-list-events]`
* cat - Show events from an event category `[ecs-list-events cat='festival']` or specify multiple categories `[ecs-list-events cat='festival, workshops']`
* limit - Total number of events to show. Default is 5. `[ecs-list-events limit='3']`
* order - Order of the events to be shown. Value can be 'ASC' or 'DESC'. Default is 'ASC'. Order is based on event date. `[ecs-list-events order='DESC']`
* date - To show or hide date. Value can be 'true' or 'false'. Default is true. `[ecs-list-events eventdetails='false']`
* venue - To show or hide the venue. Value can be 'true' or 'false'. Default is false. `[ecs-list-events venue='true']`
* excerpt - To show or hide the excerpt and set excerpt length. Default is false. `[ecs-list-events excerpt='true']` //displays excerpt with length 100
 excerpt='300' //displays excerpt with length 300
* thumb - To show or hide thumbnail image. Default is false. `[ecs-list-events thumb='true']` //displays post thumbnail in default thumbnail dimension from media settings.
* thumbsize - Specify the size of the thumbnail. `[ecs-list-events thumb='true' thumbsize='large']`
* thumbwidth / thumbheight - Customize the thumbnail size in pixels `[ecs-list-events thumb='true' thumbwidth='150' thumbheight='150']`
* message - Message to show when there are no events. Defaults to 'There are no upcoming events at this time.'
* viewall - Determines whether to show 'View all events' or not. Values can be 'true' or 'false'. Default to 'true' `[ecs-list-events cat='festival' limit='3' order='DESC' viewall='false']`
* contentorder - Manage the order of content with commas. Default to `title, thumbnail, excerpt, date, venue`. `[ecs-list-events cat='festival' limit='3' order='DESC' viewall='false' contentorder='title, thumbnail, excerpt, date, venue']`
* month - Show only specific month (in YYYY-MM format). Type `'current'` for displaying current month only or `'next'` for next month. `[ecs-list-events cat='festival' month='2024-06']`
* past - Show Outdated Events. `[ecs-list-events cat='festival' past='yes']`
* key - Hide events when the start date has passed `[ecs-list-events cat='festival' key='start date']`
* orderby - Change the ordering to the end date `[ecs-list-events orderby="enddate"]`

With [The Events Calendar Shortcode & Block Pro](https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme-faq-options&utm_content=description) you also get the following options:

* design - Shows improved design by default. Set to 'standard' for the regular one, 'compact' for a more compact listing, 'calendar' for a monthly calendar view, 'columns' to show a horizontal/columns/photo view, or 'grouped' to group events by day
* filter bar - Allow the user to filter the events shown (ie. by category, state/province, country, venue, etc)
* pagination - Allow the user to view additional pages of events
* days - Specify how many days in the future, for example `[ecs-list-events days="1"]` for one day or `[ecs-list-events days="7"]` for one week
* tag - Filter by one or more tags.  Use commas when you want to filter by multiple tags.
* id - Show a single event, useful for displaying details of the event on a blog post or page
* location (city, state/province, country) - Display events by location.  Use commas when you want to include events from multiple (ie. country='United States, Canada')
* description - Use the full description instead of the excerpt of an event in the listing
* raw_description - Avoid filtering any HTML (spacing, links, bullet points, etc) in the description
* raw_excerpt - Avoid filtering any HTML (spacing, links, etc) in the excerpt
* featured only - Show only events marked as "featured"
* date - Show only events for a specific day `[ecs-list-events date='2024-04-16']`
* year - Show only events for a specific year `[ecs-list-events year='2024']`
* date range - Show only events between certain days `[ecs-list-events fromdate='2024-05-31' todate='2024-06-15']`
* timeonly - To show just the start time of the event. `[ecs-list-events timeonly='true']`
* offset - Skip a certain number of events from the beginning, useful for using multiple shortcodes on the same page (with ads in between) or splitting into columns
* custom design - Create one or more of your own using shortcode variables or templates for use with the shortcode
* hiderecurring - To only show the first instance of a recurring event, set to 'true'

[Get The Events Calendar Shortcode & Block Pro](https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme-faq-options-bottom&utm_content=description)

= Can I use this plugin to list my events using the new WordPress 5.0 editor (Gutenberg)? =

Yes! There is now a block to list your events anywhere in a page or post, just click "+" in the top-left and search for The Events Calendar Block (under Common).

= How do I use this shortcode in a widget? =

You can put the shortcode in a text widget.

= Can I use this plugin to list my events using Elementor? =

Yes! This plugin <a href="https://eventcalendarnewsletter.com/how-to-use-the-events-calendar-shortcode-with-elementor/?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme-faq-options-bottom&utm_content=description">includes an Elementor Widget</a>.

= What are the classes for styling the list of events? =

By default the plugin does not include styling. Events are listed in ul li tags with appropriate classes for styling with a bit of CSS.

* ul class="ecs-event-list"
* li class="ecs-event" and "ecs-featured-event" (if featured)
* event title link is H4 class="entry-title summary"
* date class is time
* venue class is venue
* span .ecs-all-events
* p .ecs-excerpt

Want a better looking design without knowing any CSS?  Check out [The Events Calendar Shortcode & Block Pro](https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme-faq-design&utm_content=description)

= How do I include a list of events in a page template? =

Put this in the template where you want the events list to display:

`<?php echo do_shortcode("[ecs-list-events]"); ?>`

= How do I include a monthly calendar view instead of a list? =

The [pro version of the plugin](https://eventcalendarnewsletter.com/the-events-calendar-shortcode?utm_source=wordpress.org&utm_medium=link&utm_campaign=tecs-readme-faq-calendar&utm_content=description) has the option to put `design="calendar"` in the shortcode (or pick Calendar as the design with the block) to show a calendar view of the events you want.

== Screenshots ==

1. Show your events from The Events Calendar (by StellarWP, formerly Modern Tribe) in a list, and customize specifically which events you're displaying
2. Add a block in the page or post where you want your events to appear, and select the display options you want (new default WordPress editor or Gutenberg plugin)
3. Add a widget in Elementor to show your events in a page or post, and customize the display options you want
4. You can also add the shortcode where you want the list of events to appear on any WordPress post, page, or widget
5. Many settings you can use in the shortcode to change what details appear in the events listing

== Changelog ==

= v4.0.0 - 2026-06-07 =

##### Updates and Enhancements

+ Move the block settings to the sidebar, and adds most additional options to the block instead of having to use key/value pairs.
+ Improved logic for setting the attributes between the toggle on/off and the content order toggle.
+ Always show content order items rather than filtering and re-inserting them in a potentially different order.
+ Set default design attributes so the options show what appears in the preview correctly.


= v3.1.3 - 2026-02-05 =

##### Updates and Enhancements

+ Additional escaping for text entered into the message attribute.


= v3.1.2 - 2026-01-28 =

##### Updates and Enhancements

+ Additional escaping of options when using the block


= v3.1.1 - 2025-11-27 =

##### Updates and Enhancements

+ Updated documentation links


= v3.1.0 - 2025-04-10 =

##### Updates and Enhancements

+ Support for Bricks theme


= v3.0.1 - 2024-10-28 =

##### Updates and Enhancements

+ Improved Elementor compatibility
+ Additional help text


= v3.0.0 - 2024-06-10 =

##### New Features

+ Adds a block for Elementor! Easily add your events to any page or post using the Elementor page builder.


= v2.8.5 - 2024-02-23 =

##### Bug Fixes

+ Fixing the Order and Order By options not saving in the block

##### Updates and Enhancements

+ Optional opt-in tracking notice added


= v2.8.4 - 2023-12-03 =

##### Bug Fixes

+ Fixing documentation page


= v2.8.3 - 2023-12-03 =

##### Updates and Enhancements

+ Updated documentation link
