Companion Collections Explained
Companion collections let you work around Webflow CMS limitations like the lack of a multi-image field. Learn when to create them, how they link back to the parent, and how Trellis generates them automatically.
What is a companion collection?
A companion collection is a secondary CMS collection whose sole purpose is to hold repeating data that its parent collection cannot store in a single field. The most common reason you need one: Webflow has no multi-image field. If a property listing needs 25 photos, or an estate sale needs a scrollable gallery, those images must live in their own collection with a reference back to the parent item.
Why Webflow forces this pattern
Webflow CMS fields are single-value by design. You get one image field per entry, not an array. The only "many" relationship available is a Multi-Reference field, which links to items in another collection — it does not store raw images or files.
This means any time you need more than one of something attached to a single item, you need a companion collection to hold the extras:
- Photo galleries — one image per companion item, referenced back to the parent.
- Document attachments — PDFs, downloads, or resource links.
- Availability calendars — date ranges stored as individual items.
- Pricing tiers — multiple price points for a single product or service.
- Variant options — sizes, colors, or configurations.
How the linking pattern works
The companion collection always contains:
- A Reference field pointing back to the parent collection (e.g., "Parent Property" → Properties).
- The repeated data — an image field, a date range, a file field, or whatever the parent cannot hold in bulk.
- A sort order field (optional) — a number field so you can control display sequence.
On the Webflow side, you display companion items using a Collection List nested inside the parent's Collection Page, filtered by the reference field. This gives you a dynamic gallery, attachment list, or calendar that updates automatically when companion items are added or removed.
Real-world examples
Estate Sale → Sale Photos
An estate sale listing needs 10-40 photos. The parent collection Estate Sales has fields like title, date, address, and description. The companion collection Sale Photos has:
| Field | Type | Purpose |
|---|---|---|
| Photo | Image | The actual image |
| Sale | Reference → Estate Sales | Links back to the parent |
| Caption | Plain Text | Optional image caption |
| Sort Order | Number | Controls display sequence |
Property → Availability Calendar
A vacation rental needs blocked-out date ranges. The companion collection Availability has:
| Field | Type | Purpose |
|---|---|---|
| Property | Reference → Properties | Links back to the parent |
| Start Date | Date | Beginning of blocked period |
| End Date | Date | End of blocked period |
| Status | Option (Booked / Maintenance / Owner Use) | Why the dates are blocked |
Product → Product Variants
An e-commerce product needs multiple SKUs. The companion collection Variants has:
| Field | Type | Purpose |
|---|---|---|
| Product | Reference → Products | Links back to the parent |
| Variant Name | Plain Text | "Large / Blue" |
| Price | Number | Variant-specific price |
| SKU | Plain Text | Inventory identifier |
| In Stock | Switch | Availability toggle |
How Trellis auto-generates companion collections
When you describe a content type that includes a multi-image field, an attachment list, or a repeating sub-structure, Trellis detects the pattern and automatically creates the companion collection for you. It:
- Creates the companion collection with the correct fields.
- Adds the reference field linking back to the parent.
- Sets up the sort order field.
- Configures the sync mapping so items flow correctly from your source (Airtable, Notion, etc.) into both collections.
You do not need to manually create companion collections — Trellis handles the split. But understanding the pattern helps you design better content structures and debug layout issues.
When NOT to use a companion collection
- Fixed-size image sets — if every item has exactly 3 images (hero, thumbnail, og-image), use 3 separate image fields instead of a companion collection.
- Simple lists — if you just need a comma-separated list of tags, an Option field or Multi-Reference field is simpler.
- Rarely-used extras — if only 5% of items have attachments, consider whether the overhead of a companion collection is worth it.
Next steps
- Read Image and Gallery Fields for details on single vs. multi-image patterns.
- Read Reference Fields to understand how the linking relationship works.
- Read Planning CMS Architecture Before You Build for a broader view of structuring your collections.