PCOWidget — All Configuration Options

Live demo using Emmanuel Lutheran Church data  ·  API key 18dc5c27c3e7ee647b3ff31626a10d16

🛠 Build your own script interactively →

Layouts — data-layout

Built

Five layouts are available. Default is table if omitted.

table — Month grid (default)
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=18dc5c27c3e7ee647b3ff31626a10d16" data-layout="table"></script>

week — 7-day strip
<script src="..." data-layout="week"></script>

list — Row list with thumbnails
<script src="..." data-layout="list"></script>

cards — Image cards
<script src="..." data-layout="cards"></script>

simple — Service tiles (minimal)
<script src="..." data-layout="simple"></script>

Tag filter — data-tag

Built

Filter to events that have a specific Planning Center tag. Comma-separate multiple tag names for OR logic — e.g. data-tag="Youth,Women's Ministry" shows events tagged either tag.

Filter by tag "Worship Services" — simple layout
<script src="..." data-layout="simple" data-tag="Worship Services"></script>

Tag + featured combined — list layout
<script src="..." data-layout="list" data-featured="true" data-tag="Worship Services"></script>

Rolling 7-day window — data-this-week

Built

Shows only events in the next 7 days from today. Perfect for "This Week's Services" homepage sections. Works with any layout.

This week — simple layout (homepage use case)
<script src="..." data-layout="simple" data-this-week="true" data-title="This Week's Services"></script>

This week — cards layout
<script src="..." data-layout="cards" data-this-week="true"></script>

Week navigation — data-allow-week-nav + data-nav-align

Built

Adds Prev / Next week navigation buttons to the simple layout. The label shows "This Week" / "Next Week" / "+N Weeks" and clicking it returns to the current week. data-nav-align controls button alignment: left, center (default), or right.

Week nav — align center (default)
<script src="..." data-layout="simple" data-allow-week-nav="true" data-nav-align="center" data-title="This Week's Services"></script>

Week nav — align left
<script src="..." data-layout="simple" data-allow-week-nav="true" data-nav-align="left"></script>

Week nav — align right
<script src="..." data-layout="simple" data-allow-week-nav="true" data-nav-align="right"></script>

Show past events — data-include-past

Built

By default, events that have already ended are hidden. Set data-include-past="true" to include them — useful for archive or recap pages. Default: false.

Include past — list layout
<script src="..." data-layout="list" data-include-past="true"></script>

Exclude past (default behavior shown explicitly)
<script src="..." data-layout="list" data-include-past="false"></script>

Also accepted: "1" / "0", "True" / "False", "TRUE" / "FALSE".

Event count — data-limit

Built (max 50) "ALL" not supported yet

Controls how many events to fetch. Default: 50. Currently capped at 50 — "ALL" is not yet a valid value.

Limit 3 — good for homepage previews
<script src="..." data-layout="cards" data-limit="3"></script>

Limit 6 — cards grid
<script src="..." data-layout="cards" data-limit="6"></script>

Tile columns — data-columns

Built (simple layout)

Controls tiles per row on the simple layout. Range: 1–8. Default: 2. Always collapses to 1 column on screens ≤480px regardless of this value.

1 column
<script src="..." data-layout="simple" data-columns="1"></script>

2 columns (default)
<script src="..." data-layout="simple" data-columns="2"></script>

3 columns
<script src="..." data-layout="simple" data-columns="3"></script>

Shadow style — data-shadow

Built

Controls the container shadow color theme. Default: blue.

shadow="blue" (default)
<script src="..." data-layout="simple" data-shadow="blue"></script>

shadow="burgundy"
<script src="..." data-layout="simple" data-shadow="burgundy"></script>

shadow="standard" (neutral gray)
<script src="..." data-layout="simple" data-shadow="standard"></script>

Custom heading — data-title

Built

Overrides the heading displayed above the widget. Any string is valid. If omitted, the widget auto-generates a heading from the filter context (e.g. "Featured Events", "Worship Services").

Custom title on simple layout
<script src="..." data-layout="simple" data-title="This Week's Services"></script>

Custom title on list layout
<script src="..." data-layout="list" data-title="Upcoming Events"></script>

Mount target — data-target

Built

Mount the widget into an existing element by DOM ID instead of auto-creating a container after the script tag. Useful when you need the widget inside a specific page region.

↑ This div has id="my-custom-container" — the widget will mount here

Widget mounted into #my-custom-container
<div id="my-custom-container"></div> <script src="..." data-layout="simple" data-target="my-custom-container"></script>

Useful Combinations

Built

Real-world patterns combining multiple options.

Homepage: This week's worship services, 3-col, with week nav, burgundy shadow
<script src="..." data-layout="simple" data-tag="Worship Services" data-this-week="true" data-allow-week-nav="true" data-columns="3" data-shadow="burgundy" data-title="This Week's Services"></script>

Events page: Full month calendar, featured events only
<script src="..." data-layout="table" data-featured="true" data-title="Featured Events"></script>

Ministry page: Cards, limited to 6, with tag filter
<script src="..." data-layout="cards" data-tag="Worship Services" data-limit="6" data-shadow="standard" data-title="Worship Events"></script>

Archive page: List with past events included
<script src="..." data-layout="list" data-include-past="true" data-limit="20" data-title="Past Events"></script>

Multi-tag OR filter — data-tag="tag1,tag2"

Built

Comma-separate tag names to show events matching ANY of the listed tags (OR logic). Case-insensitive. Single tag still works exactly as before.

Two tags OR — list layout
<script src="..." data-layout="list" data-tag="Worship Services,Special Events" data-title="Worship & Special Events"></script>

Tag OR + featured filter — cards
<script src="..." data-layout="cards" data-tag="Worship Services,Special Events" data-featured="true" data-limit="6"></script>

Hide end time — data-hide-end-time

Built

Show only the start time — hides the “– 10:30 AM” portion. Applies to simple, cards, and list layouts. Useful for service tiles where end times add clutter.

Hide end time — simple layout
<script src="..." data-layout="simple" data-hide-end-time="true" data-title="Services (start times only)"></script>

Hide end time — list layout
<script src="..." data-layout="list" data-hide-end-time="true"></script>

Hide widget when empty — data-hide-if-empty

Built

When zero events match the current parameters, the widget normally renders a "No upcoming events found" box that takes up space on the page. With data-hide-if-empty="true", the entire container collapses to nothing — no border, no message, no space. Works with all layouts and all filter combinations.

Primary use case: tag-filtered or this-week widgets on pages where that ministry or service may have no upcoming events. Without this flag you get an empty box; with it the section disappears entirely until events exist.

Hide if empty — tag-filtered simple layout
<script src="..." data-layout="simple" data-tag="Men's Ministry" data-this-week="true" data-hide-if-empty="true" data-title="Men's Ministry This Week"></script>

If no Men's Ministry events exist this week, nothing renders above — no box, no space.

Hide if empty — featured cards
<script src="..." data-layout="cards" data-featured="true" data-hide-if-empty="true" data-title="Featured Events"></script>

Custom empty message — data-empty-message

BuiltNew

When nothing matches, the widget shows "No upcoming events at this time." Use data-empty-message to say something more useful instead: point visitors at your weekly service times, another page, or a phone number. Up to 200 characters.

Note: this is ignored if you also set data-hide-if-empty, since in that case the widget removes itself entirely and there is no message to show.

Default wording
<script src="..." data-layout="cards" data-tag="NoSuchTagExists"></script>

Custom wording
<script src="..." data-layout="cards" data-tag="NoSuchTagExists" data-empty-message="Nothing scheduled right now. Join us Sundays at 10:30am."></script>

Choose which tags are visible — data-show-tags

BuiltNew

Some events carry six or eight Planning Center tags. On a card layout every one of them renders as a chip, which pushes the title and details downward and makes the card look cluttered. data-show-tags is a whitelist: only the tags you name stay visible.

Match by group, not by tag. Planning Center organizes tags into tag groups (Campus, Ministry, Category, and so on). Entries in data-show-tags match either a tag group name or an individual tag name. Naming the group is almost always the better choice: with data-show-tags="Campus", a campus you add next year shows up on its own, with no change to your embed code.

This is display only. It changes which chips you see, never which events appear. To filter the events themselves, use data-tag. The two work together: filter with data-tag, then tidy up the chips with data-show-tags.

All tags (default)
<script src="..." data-layout="cards" data-limit="2"></script>

No tag chips at all
<script src="..." data-layout="cards" data-limit="2" data-show-tags="0"></script>

One tag group only
<script src="..." data-layout="cards" data-limit="2" data-show-tags="Ministry"></script>

Named tags only
<script src="..." data-layout="cards" data-limit="2" data-show-tags="Website,Highlighted"></script>

Skip to the next month with events — data-auto-advance

BuiltNew

It is the 28th of the month, the next event is nine days away, and the widget shows an empty box. data-auto-advance="2" tells the widget: if the month the visitor lands on has nothing, look ahead up to two months and show the first one that does. The month heading follows the jump, so the widget reads "September 2026" instead of claiming to show an empty August.

Keep the number small. Accepts 1 through 6. Jumping five months ahead to surface one lonely event is about as useful to a visitor as showing them last month's calendar. One or two is usually right.

Only on arrival. Auto-advance applies to the month the visitor first lands on. Once they click the month arrows, they get exactly the month they asked for, empty or not. Silently skipping past a month someone deliberately navigated to makes the arrows feel broken.

This is not an aggregate window. Auto-advance picks which single month the visitor lands on, and the month arrows still move one month per press from there. If what you want is "gather the next four months of Youth events into one grid", that is a different attribute: data-months-ahead.

Combining with data-hide-if-empty: auto-advance runs first. The widget only removes itself if no month inside the lookahead window has any events. If you want the widget to disappear the moment the current month is empty, leave auto-advance off.

Without auto-advance
<script src="..." data-layout="cards" data-tag="Men's Ministry"></script>

Look ahead up to 3 months
<script src="..." data-layout="cards" data-tag="Men's Ministry" data-auto-advance="3"></script>

Gather several months into one set — data-months-ahead

BuiltNew

The rest of the widget answers "which month am I looking at". This one answers a different question: what is coming up. data-months-ahead="4" pulls every matching event from today out to four months into a single set and drops the month arrows entirely. Point it at a tag and you have a thumbnail strip of everything in that series that is still ahead, which is what a church home page usually wants above the fold.

It is a window from today, not a run of calendar months. On the 26th of August, data-months-ahead="4" covers 26 August to 26 December. Nothing that has already finished appears, so the set shrinks through the month and refills as new events are scheduled. Accepts 1 through 12.

No month navigation, on purpose. There is no month being displayed, so there is nothing for arrows to move between and the toolbar is not drawn at all. That also means data-auto-advance and data-this-week have nothing to do here: both pick a window, and this one has already picked it. The Widget Display Builder drops them from the embed code for you.

Pair it with data-rows or data-limit. Four months of a busy calendar is a lot of tiles. A row cap keeps the block a fixed height and shows the soonest events, which is the point of putting it on a home page.

list, cards, tiles and simple only. table and week draw a calendar grid whose rows are the weeks of one month, so there is nowhere to put a four-month span. They ignore the attribute rather than quietly showing you one month of it.

Nothing in the whole window? Then the church genuinely has nothing scheduled that far out, and no setting can invent one. Add data-hide-if-empty="1" and the widget removes itself from the page instead of announcing the gap.

One month at a time (the default)
<script src="..." data-layout="tiles" data-columns="3" data-rows="1"></script>

The next 4 months, gathered
<script src="..." data-layout="tiles" data-columns="3" data-rows="1" data-months-ahead="4"></script>

Approval and publish levels — data-visibility

BuiltNew

Planning Center tracks two separate things about an event: where it sits in your approval workflow (approved, pending, rejected) and whether you have published it to Church Center. data-visibility walks down both at once. Each level shows everything the level above it showed, plus one more class of event.

Level What appears Use it for
published (default) Approved and published to Church Center. Your public website. Always.
approved The above, plus approved events not yet published. Checking what is ready to publish.
pending The above, plus events awaiting approval. Watching the approval queue.
rejected The above, plus rejected events. Everything. Troubleshooting a missing event.
This is a staging tool. Put a second widget on a staff-only page with data-visibility="pending" and your team can see what is moving through approval and how it will look once live, while the public page keeps showing only finished, published events. Never set anything other than published on a page visitors can reach.

No approval workflow? Nothing changes. If your church does not use Planning Center's approval process, every event counts as approved and only the publish setting matters.

If an event is missing from your site, check this first. The most common cause of "why isn't my event showing up" is an event that was never published in Planning Center. Open the event in PCO Calendar and confirm it is visible in Church Center. Temporarily switching a staff page to data-visibility="rejected" shows the whole calendar, which makes it obvious where the event actually sits.

Public page (default, no attribute needed)
<script src="..." data-layout="cards" data-limit="3"></script>

Staff preview page showing the whole calendar
<script src="..." data-layout="cards" data-limit="3" data-visibility="rejected" data-title="Full Calendar (Staff View)"></script>

data-include-unpublished="true" still works as shorthand for data-visibility="approved". If both are set, data-visibility wins.

Roadmap — Features Not Yet Built

Not built

These were requested and are being evaluated for implementation:

Feature Proposed Attribute Notes
Fetch ALL events (no limit) data-limit="all" Currently hard-capped at 50 in the API. Removing the cap requires a PCO API pagination loop and a decision on performance trade-offs.