Skip to navigation
Data APIWorking with the CMS

Components in Rich Text

Read and write Webflow component instances inside CMS Rich Text fields

Rich Text field values are HTML strings that can contain Webflow component instances, serialized as <wf-component> custom-element markup. On read, an instance appears inline in the field’s HTML; on write, the same markup creates or updates the instance.

Markup at a glance

A component instance is a <wf-component> element that carries the component’s identity and its property values:

<wf-component
  data-w-id="8bb3f36d-2603-9e9f-5bad-636c66e6bf82"
  component-id="5442c383-ffdb-2ba9-a482-c8008c752856"
  name="Callout"
  prop-2c007099-cf6e-023f-37c6-3a41f6dbee60="Heads up"
>
  <wf-prop name="18e15bec-b707-e9db-46c8-14860514dfee" label="Body" type="richtext">
    <p>Bring your towel.</p>
  </wf-prop>
</wf-component>
AttributeMeaning
component-idThe component definition to instantiate. Specific to your site.
data-w-idThe instance’s unique id. Omit it on create (the server assigns one); keep it on update.
nameThe component’s display name (informational).
prop-<propId>="…"A scalar property value (plain text, numbers, booleans, links).
<wf-prop name="<propId>" type="text|richtext">…</wf-prop>A text or rich-text property, whose value is nested markup.

component-id and each prop-<propId> are specific to your site’s component definitions. See Finding component and property IDs below.

Reading components

When you GET a CMS item, any component instances in a Rich Text field are returned inline as <wf-component> markup within the field’s HTML string. You can reuse that markup as the basis for a later write.

GET/v2/collections/:collection_id/items/:item_id
$curl https://api.webflow.com/v2/collections/:collection_id/items/:item_id \
> -H "Authorization: Bearer <token>"
Try it

Writing components

On POST and PATCH, the <wf-component> markup you send in a Rich Text field is what creates or updates the instance:

  • Create a new instance by including <wf-component> markup without a data-w-id — the server assigns one.
  • Update an existing instance by keeping its returned data-w-id.
  • Set scalar props as prop-<propId> attributes; set text/rich-text props as nested <wf-prop name="<propId>" type="…"> children.
POST/v2/collections/:collection_id/items
$curl https://api.webflow.com/v2/collections/:collection_id/items \
> -H "Authorization: Bearer <token>"
Try it
PATCH/v2/collections/:collection_id/items/:item_id
$curl https://api.webflow.com/v2/collections/:collection_id/items/:item_id \
> -H "Authorization: Bearer <token>"
Try it

Finding component and property IDs

component-id and prop-<propId> values come from your site’s component definitions. To look them up:

  • List the site’s components to get each component-id:
    GET/v2/sites/:site_id/components
    $curl https://api.webflow.com/v2/sites/:site_id/components \
    > -H "Authorization: Bearer <token>"
    Try it
  • List a component’s properties to get each prop-<propId>:
    GET/v2/sites/:site_id/components/:component_id/properties
    $curl https://api.webflow.com/v2/sites/:site_id/components/:component_id/properties \
    > -H "Authorization: Bearer <token>"
    Try it
  • Or GET an item that already contains the component and reuse the returned <wf-component> markup.

Constraints

A write is rejected with a 400 when the Rich Text contains a component that:

Rejected when the component…Notes
can’t be resolvedcomponent-id doesn’t match a component on the site.
contains a Collection ListCollection Lists aren’t allowed inside a Rich Text field.
populates a SlotA component with an unpopulated Slot is allowed; only populating a Slot is rejected.
includes an unknown propertyA prop-<propId> / <wf-prop> that isn’t defined on the component.
creates a new instance in a secondary localeNew instances can only be created in the primary locale.

The write is rejected as a whole — no partial writes.

Manage collections and items

Create, read, and update CMS items with the Data API.

Publishing

Stage and publish CMS content.