Events

Events listing with dates, venues, and featured images.
Events listing with dates, venues, and featured images.

Usage

The Events block queries event posts and renders them as a List, Cards grid, or Mini layout. Filter by time range — upcoming, past, ongoing, future, or all — and optionally by Event Categories.

Use it anywhere you need a schedule: tour dates, class listings, office hours, fundraisers, or conference agendas. A common pattern is two blocks on one page: one for upcoming dates and one for past dates (see Hang Ten — Shows for a live example).

Real-world example

hangtenband.com/shows uses two Events blocks on a single page:

  1. Upcoming Shows — Display set to Default (Ongoing & Future). When no dates qualify, the block shows a friendly empty state: "There are no upcoming events at this time."
  2. Past Shows — Display set to Past, Display As set to Cards, Columns set to 4, Image hidden, Title Style at h4, Show Address on with City and State, and the post Excerpt used for door times and lineups.

Each card links to a single event page with the full show detail.

Content

  • Display — Default (Ongoing & Future) (default), Ongoing, Past, Future, or All. Past events sort newest-first; upcoming sorts soonest-first.
  • Preferred Image — Featured Image (default) or Video when the event has a Video URL and no featured image
  • Category — filter by Event Categories; leave empty for all categories
  • Limit Events — when enabled, cap results with Events To Show (1–50, default 3). Leave off for full archive pages like a tour history.

Appearance

  • Display As — List (image + copy side by side), Cards (default, responsive grid), or Mini (compact grid)
  • Columns — 1–5 per row for Cards and Mini (default 3)
  • Title Style — Customizer preset for linked event titles (default unchanged)
  • Image — Default, Show, or Hide per card/list row
  • Image Aspect Ratio — golden rectangle, 1:1, 16:9, etc.
  • Excerpt — Default, Normal, Small, or Hide. The WordPress excerpt is ideal for door times, bill names, or ticket notes.
  • Link / Link Text — link style and label (default See Event); set Link to Hide for fully clickable cards without a separate CTA line
  • Spacing — vertical gap between items (XS through XL)
  • Show Address — when enabled, choose Show Street, Show City (default on), Show State (default on), Show Zip

Front-end behavior

The block queries all published events, filters in PHP by Display mode using each event's Starts and Ends dates, then renders the chosen template.

Empty states are built in: upcoming blocks show "There are no upcoming events at this time"; past blocks show "There have been no past events."

Block width

Events supports Wide (default), Full, Center, and None alignment.

Tips

  • For a tour page, stack Upcoming (list or cards) above Past (cards grid) like Hang Ten — visitors see what's next, then browse history.
  • Hide Image on dense card grids when photos aren't needed; let title, date, city, and excerpt carry the row.
  • Put door time and lineup details in the event Excerpt field — the block surfaces it on every layout.
  • For a month grid, use Events Calendar instead. For a single promoted date, use Event Countdown.