Collections and Field Types

This content was generated with the assistance of AI and should be verified against the official Webflow documentation before being relied on in production.

This sub-section’s Webflow bibliography lists the reference material consulted while preparing these pages.

This page describes Webflow Collections and their field types as they were on 2026-10-28, the date on which they were checked against the official documentation. Collections are part of the CMS, which every Site plan except the static-only tiers includes in some form: the Starter tier has a small CMS allowance, Premium has the full allowance and Team and Enterprise extend it. The page names tiers only and never quotes prices; the Plans, Workspaces, Seats and Roles page explains the tiers and CMS Limits and Scaling lists the item and Collection allowances of each. Webflow has no version numbers, so the facts are dated; the Data API examples are written against the Data API v2 and run on a Developer workspace site, which needs no paid plan.

This is the central reference page of the CMS part of the sub-section. The CMS Concepts and Content Modeling page decides which Collections a site needs and how they relate. This page explains how to build them: how a Collection is created, what each of the 16 field types stores, what Webflow generates when a field is bound to an element, what validation each type offers, which limits apply and how to correct a field that was created with the wrong type. The running example is Fernbrook Gardens, a fictitious botanical garden whose Plants, Zones and Garden Journal Collections are used throughout.

What a Collection is

A Collection is a table-like container of structured content. Each row is an item, and each column is a field. A Collection also has a URL identity: the Collection’s slug is the first path segment of every item page, so items of a Collection with the slug plants are published at /plants/<item-slug>. Webflow builds one Collection template page per Collection, a single page design that is rendered once per item; the Collection Template Pages page covers it.

Three concepts are easy to confuse.

Term Meaning

Collection

The definition: a name, a singular name, a slug and a list of fields. It holds no content by itself.

Item

One record of a Collection, with one value for each of the Collection’s fields. An item is the unit that is created, edited, drafted, archived and published.

Field

One typed column of the Collection. A field has a display name, a slug (the key used in the API and in generated code), a type, optional help text, optional validation and a required flag.

Collections are created and managed in the CMS panel of the Designer, which lists every Collection of the site, or in the CMS area of the site dashboard. Both views edit the same data. The Data API, covered at the end of this page, does the same from code.

Creating a Collection

Creating a Collection takes a few decisions that are easiest to change before content exists.

  1. Open the CMS panel and choose to create a new Collection. Webflow offers a blank Collection and, for common cases, a starter that adds the usual fields. The blank Collection is the one used here.

  2. Enter the name, for example Plants. The name is plural because it names the whole set, and it must be distinct from the other Collections of the site.

  3. Enter the singular name, for example Plant. Webflow uses it in the interface ("New Plant") and in the Data API as singularName.

  4. Check the slug that Webflow derives from the name: plants. The slug becomes the URL prefix of the item pages, so it is the one Collection property worth thinking about before the site is public. Changing it later changes every item URL, and a redirect is then needed for the old addresses.

  5. Add fields (see the next sections) and save.

Every Collection starts with two fields that cannot be removed.

  • Name: a Plain text field that titles the item. Collection lists, the item editor and the Data API all show it, which is why it should be meaningful on its own.

  • Slug: the URL segment of the item page. Webflow proposes a value from the Name when an item is created. A slug may contain lowercase letters, numbers and hyphens, and it must be unique inside the Collection.

Webflow also adds read-only system values to every item (creation date, last-updated date, publication date, the item ID and the author’s identity as a User value). They can be bound to elements and used to sort Collection lists, but they are not fields you configure.

Naming fields so that they stay usable

Field names appear in three places: the CMS editor, the dynamic binding menus of the Designer and the Data API. A few habits pay off.

  • Use a display name for people and let Webflow derive the slug for code. The slug is lowercase, with spaces turned into hyphens, and it is what the API calls the field (fieldData keys).

  • Prefer names that describe the value, not the place it is shown: Hero image is better than Image 1, and Sun requirement is better than Dropdown.

  • Fill in the help text. It is displayed under the field in the item editor and is the cheapest documentation for content editors who are not designers.

  • Be careful with renames after the site is bound to the Collection. Renaming a display name is harmless in the Designer, because bindings follow the field, but code that reads fieldData by slug (scripts, integrations, Data API clients) breaks if the slug changes.

The Fernbrook Gardens Collections

The scenario uses three Collections. The tables below are the working design that the following sections build.

Collection Slug Purpose

Plants

plants

The botanical record of each plant on display, with its images, care information, bloom period and the Zone where it grows.

Zones

zones

The named areas of the garden (Alpine Rockery, Walled Garden). A Zone is referenced by many Plants.

Garden Journal

journal

Blog posts by gardeners and volunteers, with a long-form body, a cover image, an author and a published date.

The 16 field types

Webflow offers 16 field types. The table lists them in the order of the Designer’s field picker, with the identifier the Data API uses for each. The identifiers are exact and case-sensitive.

Field type Data API type Value written through the API Typical Fernbrook use

Plain text

PlainText

a string

Plant common name, Latin name, short description

Rich text

RichText

a string of HTML

Plant care guide, journal post body

Image

Image

an object with url and optional alt

Plant hero photograph

Multi-image

MultiImage

an array of image objects

Photo gallery of a plant through the seasons

Video link

VideoLink

a string URL

Garden walk video on YouTube or Vimeo

Link

Link

a string URL

Link to a botanical database record

Email

Email

a string

Contact address of a Zone’s head gardener

Phone

Phone

a string

Phone number of the tour desk

Number

Number

a number

Mature height in centimetres

Date/Time

DateTime

an ISO 8601 string

Journal publication date

Switch

Switch

a boolean

"Rare plant" flag

Color

Color

a string in a color notation

Dominant bloom color

Option

Option

the ID of one option

Sun requirement: Full sun, Partial shade, Shade

File

File

an object with url and optional alt, or an existing file ID

Downloadable planting guide PDF

Reference

Reference

the ID of one item of another Collection

The Zone where a plant grows

Multi-reference

MultiReference

an array of item IDs

Companion plants that grow well together

The Data API also reports a User value on items (the creator and last editor). It is read-only and is not a field you can add to a Collection, so it does not count among the 16. The final section of the page returns to the API values in detail.

The sections below describe each type in the same structure: what it stores, the settings it offers, how it is bound to an element and what Webflow generates. Reference and multi-reference fields are introduced here and treated in depth on Reference and Multi-Reference Fields.

flowchart LR F[Field type] --> T[Text-like] F --> M[Media] F --> V[Value-like] F --> R[Relations] T --> T1[Plain text] T --> T2[Rich text] T --> T3[Link] T --> T4[Email] T --> T5[Phone] T --> T6[Video link] M --> M1[Image] M --> M2[Multi-image] M --> M3[File] V --> V1[Number] V --> V2[Date/Time] V --> V3[Switch] V --> V4[Color] V --> V5[Option] R --> R1[Reference] R --> R2[Multi-reference]

Plain text

A Plain text field holds unformatted text and is the right type for names, titles, short descriptions and any value that a content editor must not be able to style. Because it carries no formatting, the output is clean and predictable.

Settings:

  • Single line or multiple lines: chooses the input the editor sees. A multi-line plain text field keeps line breaks in the editor but renders as one text node unless the element is styled to preserve them.

  • Minimum and maximum character count: optional. The editor refuses a value outside the range, which makes the field a cheap guard against empty titles or runaway descriptions.

  • Required, help text and, as for every field, a display name and a slug.

A Plain text field can be bound to any text element except a Rich text element: a heading, a paragraph, a text link or a block’s text content. It can also be bound to a link’s address or to element settings such as the alt text of an image (see the alt-text pattern below).

Generated output for a Heading bound to the Name field of the Plants Collection, repeated for each item in a Collection list:

<h3 class="plant-card__title">Lavandula angustifolia</h3>

Source: Webflow Help Center: Plain text field

Pitfalls: a Plain text field does not escape or interpret HTML for display, but characters such as < and & are encoded when the page is generated, so they appear as typed. If an editor needs bold or links inside the value, the type is wrong; use Rich text.

Rich text

A Rich text field holds long-form content with formatting: headings, paragraphs, lists, block quotes, inline links, images, embedded video and, for Webflow content, embedded components and custom embeds. It is the right type for the body of a Garden Journal post or the care guide of a plant.

The editor works inside the Designer’s content editing mode on the canvas, or in the CMS editor. The author formats text with a toolbar, and the design of every element a Rich text field can contain is defined once, on a Rich text element, by styling its descendant tags (h2, p, a, ul, figure). Editors choose the structure and designers control the looks.

Webflow generates the content inside a wrapper with the class w-richtext:

<div class="journal-body w-richtext">
  <h2>Pruning lavender in late summer</h2>
  <p>Cut back to just below the old flower spikes, keeping at least two pairs of leaves.</p>
  <figure class="w-richtext-figure-type-image w-richtext-align-fullwidth">
    <div><img src="https://example.invalid/lavender.jpg" alt="Lavender after pruning"></div>
  </figure>
  <ul role="list">
    <li>Prune after flowering ends.</li>
    <li>Never cut into old wood.</li>
  </ul>
</div>

Source: Webflow Help Center: Rich text field overview

The markup above is simplified: the exact classes Webflow emits for embedded media and alignment vary, so style the Rich text element’s tags through the Designer rather than depending on the generated class names.

Practical rules:

  • The editor always chooses the outer structure. If the Journal needs a fixed layout (hero, lede, body), split it into separate fields (cover image, Plain text intro, Rich text body) and bind each one separately, so the layout cannot be broken by editing.

  • Images inside a Rich text field need alt text entered at upload time, like any other image; the field does not add it.

  • Code blocks are not supported through the Data API: a value that contains a code block is stored as an empty string, so imports and integrations must not send them.

  • The Data API reads and writes Rich text as an HTML string. Treat it as untrusted HTML if it comes from outside the CMS, and sanitise it before rendering it anywhere other than a Webflow page.

Image

An Image field holds a single image. Webflow stores the file in its asset library, shows a preview in the editor and records the alt text. The field is bound to an Image element, to a background image of any block, or to any element that accepts an image.

Settings:

  • Minimum and maximum dimensions and aspect ratio, set in the Collection settings. Webflow announced these image validations in its changelog, and they let a Collection insist on, for example, 1600 by 900 pixel hero images so layouts do not break when an editor uploads a small photograph.

  • Required, help text, display name and slug.

Through the API an image must be reachable at a public URL and may be at most 4 MB.

Generated output for an Image element bound to a Plant’s hero image:

<img src="https://example.invalid/plants/lavender-hero.jpg"
     srcset="https://example.invalid/plants/lavender-hero-p-500.jpg 500w,
             https://example.invalid/plants/lavender-hero.jpg 1600w"
     sizes="(max-width: 991px) 100vw, 800px"
     alt="Lavender in flower in the Walled Garden"
     loading="lazy"
     class="plant-hero">

Source: Data API: Field types and item values

The responsive srcset and the lazy loading come from Webflow’s image handling, which Images and Assets explains. A bound image whose alt text is empty renders an empty alt, which tells assistive technology to skip it.

Multi-image

A Multi-image field holds an ordered list of images. It is the right type for a gallery that belongs to one item, such as the same plant photographed in each season. The editor reorders the images by dragging them.

A Multi-image field cannot be bound to an Image element directly: it is displayed by binding a Collection list to the field, so that the list’s items are the images. A nested Collection list inside the item template page repeats an Image element for every picture. The Collection Template Pages page walks through the gallery. In the API a Multi-image field is an array of objects, each with a url and an optional alt; the same 4 MB limit per image applies.

Generated output (a gallery built from a nested list):

<div class="gallery w-dyn-list">
  <div role="list" class="gallery__items w-dyn-items">
    <div role="listitem" class="w-dyn-item">
      <img src="https://example.invalid/plants/lavender-spring.jpg" alt="Lavender in spring" loading="lazy">
    </div>
    <div role="listitem" class="w-dyn-item">
      <img src="https://example.invalid/plants/lavender-summer.jpg" alt="Lavender in summer" loading="lazy">
    </div>
  </div>
</div>

Source: Data API: Field types and item values

The w-dyn-list, w-dyn-items and w-dyn-item classes are the wrapper classes Webflow adds to every Collection list. They are also the hooks that custom CSS and scripts use to find lists.

Video link

A Video link field holds the URL of a video hosted on a video platform. Webflow accepts YouTube and Vimeo links, shows a preview in the editor and exposes the field to a Video element, which embeds the player. Links to other video hosts cannot be imported into the field, so a Collection that needs another host should use a Link field and a custom embed.

A bound Video element renders an embedded player in an iframe. The embed loads third-party code from the video host when a visitor opens the page, which has privacy implications (cookies and tracking by the host); choose a privacy-friendly embed option of the host, or a click-to-load pattern, when the audience requires it.

<div class="w-embed-youtubevideo plant-video">
  <iframe src="https://www.youtube.com/embed/VIDEO_ID?rel=0"
          title="Walking the Alpine Rockery"
          allowfullscreen loading="lazy"></iframe>
</div>

Source: Data API: Field types and item values

VIDEO_ID is a placeholder. Webflow derives the embed address from the stored link.

Link

A Link field holds a URL. It is bound to the address of a button, a text link or a link block, and the editor sees a plain input. Use it when the destination is data, such as the record of a plant in an external botanical database, and not a relation to another item of the site (that is a Reference field).

The field stores the string exactly as entered, so a value without a scheme such as example.com is treated as a relative path by browsers. Teach editors to enter full addresses, or validate the value in an import script.

<a class="button" href="https://example.invalid/database/lavandula-angustifolia" target="_blank" rel="noopener">
  Botanical record
</a>

Source: Data API: Field types and item values

Email

An Email field holds an email address and validates its format in the editor. Bound to a link, it can produce a mailto: address; Webflow writes the mailto: scheme into the link when the Email field is chosen as the link target.

<a href="mailto:rockery@fernbrook.example">rockery@fernbrook.example</a>

Source: Data API: Field types and item values

Addresses placed in published pages are easy for harvesting bots to collect; consider a contact form instead of publishing a personal address of a staff member.

Phone

A Phone field holds a telephone number. Bound to a link it produces a tel: address, which makes the number tappable on phones. The Data API stores the value as a string, and the reference example uses digits only. Store the number in a consistent international format so that the tel: link works from any country.

<a href="tel:+15550100">+1 555 0100</a>

Source: Data API: Field types and item values

Number

A Number field holds an integer or a decimal. Use it for values you may want to sort or filter on, such as the mature height of a plant in centimetres or the number of seats at a workshop. A Collection list can sort by a Number field, which is the reason to use this type instead of a Plain text field that contains digits.

Settings include the allowed decimal places and an optional minimum and maximum, which stop obviously wrong values. Webflow formats the number when it is bound to a text element, using the options of the binding. Currency formatting of a Number field is a display choice and does not turn the field into a price; prices belong to the Ecommerce product model, which the Ecommerce Overview page describes.

<div class="plant-fact">
  <span class="plant-fact__label">Mature height</span>
  <span class="plant-fact__value">60</span> cm
</div>

Source: Data API: Field types and item values

Date/Time

A Date/Time field holds a date, or a date with a time, in a calendar and clock editor. Use it for event start times and for journal publication dates, and sort Collection lists on it to show the newest or the upcoming items first.

In the Data API the value is an ISO 8601 string, read back in UTC, for example 2026-09-14T09:00:00.000Z. The binding offers display formats (long, short, numeric, with or without the time). Two points need care.

  • The stored instant is absolute, but the displayed date uses the viewer’s time zone settings of the site unless the binding is formatted otherwise. An event that begins at 09:00 local time can therefore show on the previous day in another time zone when it is stored at midnight UTC; store the real start instant and format it consciously.

  • A Date/Time field is not the same as the item’s publication date system value, which records when Webflow published the item. Use a Date/Time field when editors must control the date shown.

<time class="journal-date" datetime="2026-09-14T09:00:00.000Z">September 14, 2026</time>

Source: Data API: Field types and item values

Switch

A Switch field holds a boolean: on or off. It is the field type behind "yes/no" decisions, such as Rare plant, Featured or Hide from the home page. It has two uses that matter.

  • Filtering: a Collection list can include only the items whose switch is on, which builds a "Featured plants" strip without any code.

  • Conditional visibility: an element can be shown or hidden depending on a switch, for example a "Rare" badge that only appears on rare plants. The Conditional Visibility and Dynamic Embeds page covers the rules.

Conditional visibility removes the element from the generated HTML for items where the condition is false, rather than hiding it with CSS, so hidden content does not reach the visitor’s browser.

<!-- Output for a rare plant; for a common plant the span is not in the page -->
<span class="badge badge--rare">Rare</span>

Source: Data API: Field types and item values

Color

A Color field holds one color, chosen in a picker in the editor. It is typically used for a category tint, a bloom color or a theme color of a Zone. A Color field can be bound to the text color, the background color or the border color of an element, and it can also be written into an embed or a style attribute.

The Data API accepts these notations: #RGB, #RGBA, #RRGGBB, #RRGGBBAA, rgb() and rgba(), hsl() and hsla(), CSS color names such as orchid, and transparent. The CSV importer accepts color names, hex codes and RGBA values, and a hex code needs its leading hash.

A well-known pattern passes the color to CSS through a custom property in an embed, so that a single class can use it for several properties:

<div class="zone-card" style="--zone-color: #5a7d3f">
  <h3 class="zone-card__title">Walled Garden</h3>
</div>
.zone-card {
  border-top: 6px solid var(--zone-color);
}
.zone-card__title {
  color: var(--zone-color);
}

Source: Data API: Field types and item values

Contrast is the editor’s responsibility: a Color field has no minimum contrast check, so a pale color used as text on white can fail accessibility requirements. The Accessibility page covers contrast and the Audit panel.

Option

An Option field holds one value chosen from a list that the designer defines when creating the field. Options are the right type for a closed vocabulary: sun requirement, difficulty, event category. Editors cannot invent new values, which keeps the data consistent and makes filtering reliable.

Settings and behaviour:

  • The designer lists the options by name. Webflow gives each an internal ID.

  • The editor picks one value in a dropdown, radio-style list or checkbox presentation, depending on the Webflow version of the editor.

  • On CSV import every distinct value in the column becomes an option, up to 100 options. An import with more than 100 distinct values should use a Reference field instead.

  • In a Collection list the Option can drive filters and conditional visibility, for example "show the shade-plant tip only for plants whose Sun requirement is Shade".

  • In the Data API an option is read and written by its ID, not by its name. The ID is read from the Collection’s field definition (validations.options), which is why an importer first fetches the Collection details.

Because an option is bound as text, the displayed value is the option’s name:

<span class="plant-fact__value">Partial shade</span>

Source: Data API: Field types and item values

A tool that renames an option in the Designer changes only its label for the editors and the pages; the ID stays. Code that compared against the name breaks, while code that compared against the ID does not.

File

A File field holds one uploaded document: a PDF planting guide, a spreadsheet, an audio file. The editor uploads a file or picks one from the asset library, and Webflow serves it from its CDN. It is bound to the address of a link or a button, which makes a "Download the planting guide" call to action.

Through the Data API a new file is uploaded from a public URL, an existing file can be referenced by its fileId, and an optional alt describes it. The API reference states no size limit for File fields, so check the limit that the Help Center gives for the plan before importing large documents.

<a class="button" href="https://example.invalid/files/lavender-planting-guide.pdf" download>
  Planting guide (PDF)
</a>

Source: Data API: Field types and item values

Files are public once the site is published, even if the page that links to them is password-protected or hidden from search engines; the address of the file is enough to download it. Put nothing confidential in a File field, and see Password Protection and Site Search for what protection covers.

Reference

A Reference field points at one item of another Collection, or of the same Collection. A Plant belongs to one Zone, so the Plants Collection has a Zone field that references the Zones Collection. The editor chooses the Zone from a list of the Zones' names. In the Data API the value is the referenced item’s ID, and the field is created with the Collection to reference in its metadata (collectionId).

A Reference field is bound by opening the referenced item’s own fields inside the current item’s context: the plant’s card can show the Zone’s name and color because the Zone is reachable from the Plant. The referenced item must be published for its data to show on a published page.

<a class="zone-chip" style="--zone-color: #5a7d3f" href="/zones/walled-garden">Walled Garden</a>

Source: Data API: Field types and item values

There is a limit of 10 Reference and Multi-reference fields per Collection (20 on Enterprise), covered below.

Multi-reference

A Multi-reference field points at several items of another Collection: a plant’s companion plants, an event’s speakers, a journal post’s topics. The editor picks any number of items. In the Data API the value is an array of item IDs, and the field is created with a collectionId, as for Reference.

A Multi-reference field is displayed by binding a Collection list to the field, so that the list’s items are the referenced items. Order follows the order the editor chose. A Collection list bound to a Multi-reference field is a nested list when placed inside another list, and it counts against the nested-list limits (up to 10 nested lists per page and 100 nested items per parent).

<div class="w-dyn-list">
  <div role="list" class="w-dyn-items">
    <div role="listitem" class="w-dyn-item"><a href="/plants/salvia-nemorosa">Salvia nemorosa</a></div>
    <div role="listitem" class="w-dyn-item"><a href="/plants/echinacea-purpurea">Echinacea purpurea</a></div>
  </div>
</div>

Source: Data API: Field types and item values

Choose between Reference and Multi-reference by the cardinality of the relation, not by convenience: one Zone per plant is a Reference; many companions per plant is a Multi-reference. The next page of the CMS series, Reference and Multi-Reference Fields, builds both relations for Fernbrook.

Choosing a type: a decision guide

When a value could fit several types, pick the most specific one, because specificity unlocks filtering, sorting, validation and binding options that a general type does not have.

The value is…​ Use Not

A short label or title

Plain text

Rich text (editors can add stray formatting)

A body that editors must format

Rich text

Plain text with HTML typed in by hand

One of a few fixed choices

Option

Plain text (typos, inconsistent spelling)

A choice from a growing list, shared by many items

Reference to a small Collection

Option (limited to a designer-defined list, and 100 on import)

A yes/no decision

Switch

Option with "Yes" and "No"

A quantity to sort or filter by

Number

Plain text containing digits

A moment in time

Date/Time

Plain text containing a date

A document to download

File

Link to a file hosted elsewhere, when Webflow can host it

A URL of an external page

Link

Plain text

Field settings

Every field has the same basic settings, and some types add more.

Setting Effect

Display name

The label in the editor and in the binding menus.

Slug (field key)

The key used in the Data API’s fieldData and in generated code. It is derived from the display name, lowercase, with spaces turned into hyphens.

Help text

A hint under the field in the item editor.

Required

The item cannot be completed without a value for this field (see the next section).

Validation

Type-specific: minimum and maximum characters for Plain text, minimum and maximum values for Number, size and aspect ratio for Image.

Options

For Option fields only: the list of allowed values.

Referenced Collection

For Reference and Multi-reference fields only: the Collection the field points to.

Required fields

A required field cannot be left empty. Webflow marks required fields in the item editor and refuses to complete an item whose required fields are empty. The Name and Slug of every item are always required.

Marking a field required is a content-quality decision with a cost. Think about it from the editor’s side.

  • Require fields that the page cannot be understood without: the Name, the Slug, the cover image of a journal post when the layout depends on it.

  • Do not require fields that are sometimes unknown: a plant whose bloom period is not yet confirmed would force editors to invent a value. Leave the field optional and use conditional visibility so that a missing value hides its label, rather than showing a blank "Bloom period:" row.

  • Adding a required field to a Collection that already has items does not fill the existing items. Add the field as optional, fill the existing items, then mark it required.

A Collection list, an element or a link bound to an empty optional field renders nothing for that value, or an empty attribute. Conditional visibility is how designers avoid empty labels and empty containers.

Through the Data API isRequired is set when a field is created and can be changed afterwards with the update-field endpoint; the endpoint changes the display name, the help text and the required flag, and not the type or the slug. Field validation (the character limits and size rules above) is not available through the API: set it in the Designer.

The alt-text-field pattern

Images in a Collection need alt text, and the Image field already stores an alt text for the picture. Editors, however, often forget it, and the alt text of a CMS image is easy to leave empty. The pattern: add a Plain text field named Hero image alt, make it required, and bind the Image element’s alt text to that field instead of to the picture’s own alt value.

The effect is that the editor cannot finish a Plant without describing the hero photograph, and the description is visible in the item editor next to the image rather than hidden in an asset panel. The field also gives the Data API an explicit place to write the description during imports.

<img class="plant-hero" src="https://example.invalid/plants/lavender-hero.jpg"
     alt="Lavender in full flower along the Walled Garden path" loading="lazy">
{
  "fieldData": {
    "name": "Lavandula angustifolia",
    "slug": "lavandula-angustifolia",
    "hero-image": { "url": "https://example.invalid/plants/lavender-hero.jpg", "alt": "Lavender in full flower" },
    "hero-image-alt": "Lavender in full flower along the Walled Garden path"
  }
}

Source: Data API: Create Items

Write alt text that says what the image shows for a visitor who cannot see it, in a short sentence, without "image of". A purely decorative image should have an empty alt text, and for those an optional alt field that is allowed to stay empty is better than a required one. The same pattern works for a video’s title, which the player’s title attribute should carry. The book Webflow by Example shows this CMS alt-text field, and the pattern is still valid; what changed is that the Image field now stores its own alt text too, so the pattern is a safety net and a bulk-import convenience, not the only way. The Accessibility page covers alt text in general.

Limits

Collections have fixed ceilings. They are the first thing to check when a model grows.

Limit Value Notes

Fields per Collection

60

Raised from 30 in 2024; many tutorials and the book Webflow by Example still say 30. Enterprise next-gen CMS allows 100.

Reference and multi-reference fields per Collection

10

Counted together. Enterprise allows 20.

Items per site

Per plan

Starter has a small allowance, Premium 20,000 and Team and Enterprise more. See the CMS Limits and Scaling page.

Collections per site

Per plan

Starter 20, Premium 40, Team 100.

Items in one Collection list

100 by default

Use an offset or pagination for more; see the Collection Lists page.

Collection lists per page

40

Nested lists: 10 per page and 100 nested items per parent.

Image size through the API

4 MB

Per image, from a public URL.

Options created by CSV import

100

Each distinct value becomes one option.

Sources for the limits are the Webflow Help Center article on dynamic content limits and the Data API changelog. The 60-field ceiling includes the default Name and Slug fields in the counts shown by the Designer; check the field counter in the Collection settings rather than counting by hand.

Hitting a limit has predictable consequences. At the field ceiling the Designer refuses to add another field. At the reference ceiling a new relationship must be modelled differently: replace a rarely used reference with an Option, or place several related values in a small "join" Collection. At the items ceiling publishing new items fails until older items are deleted, archived items still count, or the plan changes. See CMS Limits and Scaling for the strategies.

Source: Webflow Help Center: Dynamic content limits

Changing a field’s type

A field’s type cannot be changed after it is created. The Designer offers no "convert" command, and the Data API’s update-field endpoint accepts only the display name, the help text and the required flag. A Plain text field cannot become a Number field, and a Reference cannot become a Multi-reference.

This is a deliberate protection: conversion would have to guess how to reinterpret existing values on every item, element binding and API client that uses the field. The documented path is a migration in four steps, and the book Webflow by Example describes the same recipe.

flowchart TD A[Wrong field exists with data] --> B[Add a new field with the correct type] B --> C[Copy values: CSV round trip or Data API script] C --> D[Rebind every element, filter, sort and embed to the new field] D --> E[Publish and check pages] E --> F[Delete the old field]

The safe migration recipe

The example changes the Mature height field of the Plants Collection from a Plain text field (values like "60 cm") to a Number field, so that Collection lists can sort plants by height.

  1. Back up first. Create a site backup so that the previous structure can be restored. See Backups and Recovery.

  2. Add the new field with the correct type and a slightly different name, Height (cm), whose slug becomes height-cm. The old field stays in place. Do not delete anything yet.

  3. Copy the values. For a few items, edit by hand. For many items, export the Collection to CSV, transform the column in a spreadsheet or a script (for example, remove "cm" and keep digits), and import the file back with the item IDs so that existing items are updated. The CSV Import and Export page lists the format rules. For very large Collections use the Data API.

  4. Rebind the Designer. Open the template page and every page with a list that used the old field. Replace each binding with the new field, and review sorts, filters and conditional visibility, which are bindings too. Check custom embeds and scripts that read the field slug.

  5. Publish and verify in a staging environment or a branch if the plan allows, then publish the site.

  6. Delete the old field after the site has been published and verified. Deleting a field removes its values from every item, so do it last, and only after the backup exists.

The Data API version of step 3 reads each item and writes the converted value:

import { WebflowClient } from "webflow-api";

const client = new WebflowClient({ accessToken: process.env.WEBFLOW_API_TOKEN });
const collectionId = process.env.PLANTS_COLLECTION_ID;

const { items } = await client.collections.items.listItems(collectionId, { limit: 100 });

for (const item of items) {
  const text = item.fieldData["mature-height"] ?? "";
  const digits = Number.parseFloat(text.replace(/[^0-9.]/g, ""));
  if (Number.isNaN(digits)) continue;
  await client.collections.items.updateItem(collectionId, item.id, {
    fieldData: { "height-cm": digits },
  });
}

Source: Data API: Create Items

The snippet uses the webflow-api package (version 3.3.4 on 2026-10-28), a token from the environment and the Developer workspace site of the examples; the exact method names and the paging of results should be checked against the SDK reference of the pinned version before it is run, and a loop over more than 100 items must page through the results with the offset. Note that PATCH updates to staged items are not visible until the items are published.

The migration exposes a common mistake. If an element is bound to the old field and the field is deleted before the rebinding, the element loses its content and the Designer reports a broken binding. Rebinding before deleting is the whole point of the order above.

Fields and the generated page

A bound field produces ordinary markup in the published HTML, plus a few Webflow classes. Knowing what is generated explains many surprises.

  • Collection list wrappers: w-dyn-list, w-dyn-items, w-dyn-item around every list, an w-dyn-empty container for the empty state, and w-dyn-bind-empty on an element whose bound field is empty.

  • Bindings are evaluated at publish time. The static HTML contains the item values; changing an item in the CMS does not change the live page until the site or the item is published.

  • Draft and archived items are not rendered. Draft items stay out of published pages even when a site is published.

  • Empty values: an empty optional field renders an empty element. The element is still in the page, with its padding and margins, unless conditional visibility removes it.

  • Escaping: text is HTML-escaped when it is bound to text; Rich text is emitted as HTML. A script in a Rich text field is not executed, but an HTML embed in a Rich text field is trusted markup, so only trusted editors should be able to add one.

<div class="plant-list w-dyn-list">
  <div role="list" class="plant-list__items w-dyn-items">
    <div role="listitem" class="plant-card w-dyn-item">
      <h3 class="plant-card__title">Lavandula angustifolia</h3>
      <div class="plant-card__bloom w-dyn-bind-empty"></div>
    </div>
  </div>
  <div class="w-dyn-empty"><div>No items found.</div></div>
</div>

Source: Webflow Help Center: Manage CMS Collections

The w-dyn-empty block is hidden by Webflow when the list has items, and shown when it does not; designers customise it, see Collection Lists.

The Data API and field types

Everything above can be done from code with the CMS endpoints of the Data API v2, which the Data API: CMS page covers fully. This section shows the values that are relevant to field types, so that the Designer names and the API names can be matched.

Creating a Collection with fields

POST /v2/sites/{site_id}/collections creates a Collection and, in the same call, its custom fields. The token needs the cms:write scope. displayName and singularName are required. The Name and Slug fields are created automatically.

POST https://api.webflow.com/v2/sites/SITE_ID/collections
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
{
  "displayName": "Plants",
  "singularName": "Plant",
  "slug": "plants",
  "fields": [
    { "type": "PlainText", "displayName": "Latin name", "slug": "latin-name", "isRequired": true,
      "helpText": "Botanical name in italics on the page" },
    { "type": "RichText", "displayName": "Care guide", "slug": "care-guide" },
    { "type": "Image", "displayName": "Hero image", "slug": "hero-image", "isRequired": true },
    { "type": "PlainText", "displayName": "Hero image alt", "slug": "hero-image-alt", "isRequired": true },
    { "type": "MultiImage", "displayName": "Seasonal gallery", "slug": "seasonal-gallery" },
    { "type": "Number", "displayName": "Height (cm)", "slug": "height-cm" },
    { "type": "Switch", "displayName": "Rare plant", "slug": "rare-plant" },
    { "type": "Color", "displayName": "Bloom color", "slug": "bloom-color" },
    { "type": "Option", "displayName": "Sun requirement", "slug": "sun-requirement",
      "metadata": { "options": [ { "name": "Full sun" }, { "name": "Partial shade" }, { "name": "Shade" } ] } },
    { "type": "Reference", "displayName": "Zone", "slug": "zone",
      "metadata": { "collectionId": "ZONES_COLLECTION_ID" } }
  ]
}

Source: Data API: Create Collection

SITE_ID, YOUR_API_TOKEN and ZONES_COLLECTION_ID are placeholders: in a real script the token comes from an environment variable and the identifiers from earlier responses. Because the Zone field references the Zones Collection, the Zones Collection must exist first.

Adding one field later

POST /v2/collections/{collection_id}/fields adds a single field to an existing Collection. Bulk creation of fields is not supported by this endpoint, so a loop of calls, or a new Collection created with all fields at once, is the way to add several.

curl --request POST "https://api.webflow.com/v2/collections/$PLANTS_COLLECTION_ID/fields" \
  --header "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "Option",
    "displayName": "Difficulty",
    "isRequired": false,
    "metadata": { "options": [ { "name": "Easy" }, { "name": "Moderate" }, { "name": "Demanding" } ] }
  }'

Source: Data API: Create Collection Field

The response returns the created field with its id and isEditable flag. A field whose isEditable is false is a system field that cannot be modified.

Updating a field

PATCH /v2/collections/{collection_id}/fields/{field_id} changes only displayName, helpText and isRequired. It cannot change the type or the slug, which is the API form of the rule that a field’s type cannot be changed.

curl --request PATCH "https://api.webflow.com/v2/collections/$PLANTS_COLLECTION_ID/fields/$FIELD_ID" \
  --header "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "helpText": "Mature height in centimetres", "isRequired": true }'

Source: Data API: Update Collection Field

Writing item values

Item values are written in fieldData, keyed by field slug. name and slug are always required. Items are created as drafts (isDraft is true by default); set it to false to queue the item for the next site publish. One request creates at most 100 items, counting each locale variant.

POST https://api.webflow.com/v2/collections/PLANTS_COLLECTION_ID/items/insert
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
{
  "items": [
    {
      "isDraft": false,
      "fieldData": {
        "name": "Lavandula angustifolia",
        "slug": "lavandula-angustifolia",
        "latin-name": "Lavandula angustifolia",
        "care-guide": "<p>Full sun, free-draining soil. Prune after flowering.</p>",
        "hero-image": { "url": "https://example.invalid/plants/lavender-hero.jpg", "alt": "Lavender in flower" },
        "hero-image-alt": "Lavender in full flower along the Walled Garden path",
        "seasonal-gallery": [
          { "url": "https://example.invalid/plants/lavender-spring.jpg", "alt": "Lavender in spring" },
          { "url": "https://example.invalid/plants/lavender-summer.jpg", "alt": "Lavender in summer" }
        ],
        "height-cm": 60,
        "rare-plant": false,
        "bloom-color": "#8a6fb3",
        "sun-requirement": "OPTION_ID_FULL_SUN",
        "zone": "ZONE_ITEM_ID"
      }
    }
  ]
}

Source: Data API: Create Items

The response is 202. OPTION_ID_FULL_SUN and ZONE_ITEM_ID are placeholders: the option ID comes from the Collection’s field definition and the Zone ID from listing the Zones items. A 409 response means that the item already has a variant in a requested locale; 400 means a malformed body, such as an unrecognised property.

API value reference

type Designer field Write format Read format

PlainText

Plain text

string

string

RichText

Rich text

HTML string; code blocks become an empty string

HTML string

Image

Image

{ "url": "...", "alt": "..." }

{ "fileId", "url", "alt" }

MultiImage

Multi-image

array of image objects

array of image objects with fileId

VideoLink

Video link

URL string

URL string

Link

Link

URL string

URL string

Email

Email

string

string

Phone

Phone

string

string

Number

Number

number (integer or decimal)

number

DateTime

Date/Time

ISO 8601 string or date

ISO 8601 string

Switch

Switch

boolean

boolean

Color

Color

color string (hex, rgb(), hsl(), named, transparent)

string

Option

Option

option ID string

option ID string

File

File

object with url (and optional alt), or an existing file reference

object with fileId, url and optional alt

Reference

Reference

item ID string

item ID string

MultiReference

Multi-reference

array of item ID strings

array of item ID strings

(read-only) User

created by and last updated by

not writable

user ID string

Source: Data API: Field types and item values

The 16 writable rows match the 16 Designer field types; the User row is read-only and is listed for completeness.

Common pitfalls

  • Choosing a type for how it looks today. A date stored as Plain text cannot be sorted by date. Pick the type for what the value is.

  • Modelling a repeating group as many fields. Fifteen fields called Photo 1 to Photo 15 eat the 60-field budget; a Multi-image field or a related Collection does not.

  • Relying on Option for a vocabulary that grows. Options are fixed by the designer. If editors keep asking for new values, make the vocabulary a Collection and use a Reference.

  • Forgetting that everything referenced must be published. A published plant whose Zone item is still a draft shows an empty Zone.

  • Renaming slugs after launch. Scripts, integrations and the Data API depend on field slugs, and item slugs depend on the URL structure.

  • Treating File fields as private. A published file is public to anyone with its address.

  • Pasting HTML into Plain text and expecting formatting. A Plain text field shows the tags as text.

  • Skipping the migration order. Rebind first, delete last, back up before anything.

Quick reference

Task Where

Create a Collection

CMS panel, new Collection (name, singular name, slug); or POST /v2/sites/{site_id}/collections

Add a field

Collection settings, add a field; or POST /v2/collections/{collection_id}/fields

Make a field required

Field settings, Required; or isRequired through the API

Change a field’s name or help text

Field settings; or PATCH on the field

Change a field’s type

Not possible: add a new field, copy values, rebind, delete the old one

Count fields

Collection settings; the ceiling is 60 per Collection

References