> This page is for Data API, version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developers.webflow.com/data/v2.0.0/llms.txt
> - v2 Beta: https://developers.webflow.com/data/v2.0.0-beta/llms.txt
> - v1: https://developers.webflow.com/data/v1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.webflow.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.webflow.com/_mcp/server.

# Components in Rich Text

> Read and write Webflow component instances inside CMS Rich Text fields with the Data API

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:

```html
<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>
```

| Attribute                                                    | Meaning                                                                                  |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `component-id`                                               | The component definition to instantiate. Specific to your site.                          |
| `data-w-id`                                                  | The instance's unique id. Omit it on create (the server assigns one); keep it on update. |
| `name`                                                       | The 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.                          |

> **Note**
>
> `component-id` and each `prop-<propId>` are specific to your site's component definitions. See [Finding component and property IDs](#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.

## 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.

## 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`:
* List a component's properties to get each `prop-<propId>`:
* 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 resolved                            | `component-id` doesn't match a component on the site.                                    |
| contains a Collection List                   | Collection Lists aren't allowed inside a Rich Text field.                                |
| populates a Slot                             | A component with an **unpopulated** Slot is allowed; only populating a Slot is rejected. |
| includes an unknown property                 | A `prop-<propId>` / `<wf-prop>` that isn't defined on the component.                     |
| creates a new instance in a secondary locale | New instances can only be created in the primary locale.                                 |

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

## Related

#### [Manage collections and items](/data/docs/working-with-the-cms/manage-collections-and-items)

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

#### [Publishing](/data/docs/working-with-the-cms/publishing)

Stage and publish CMS content.