Working with Rich Text Embeds

To follow along you'll need a project with a model, and a Rich Text field. Here's a preview of my project before we get started with enabling embeds:

Next if you edit the Rich Text field it's here you can enable embeds, and select the other content models you want to allow to be embedded.

Now with embeds enable, we have 3 ways to embed these when editing content:

If we first select the Link we can choose to use a regular href, or by selecting an existing content entry.

If you saved this content and queried for the AST using the Hygraph Content API you'd get an AST that looks like:

"children": [
  {
    "type": "paragraph",
    "children": [
      {
        "text": "Did you know you can embed "
      },
      {
        "type": "link",
        "nodeId": "ckz5njfa8ij7m0b05xxqd1ap2",
        "children": [
          {
            "text": "link"
          }
        ],
        "nodeType": "Page"
      },
      {
        "text": "?"
      }
    ]
  }
]

We can see from the response we have an array of children that contain objects of nodes that either contain content, or further children. We can see the second child is of the type link. We can also see this is of the nodeType Page, and we have the nodeId.

Right now all we now about the embedded link node is that it's a Page. We'll need to extend our GraphQL query to use inline fragments to fetch the references:

{
  page(where:{ id: "..." }) {
    content {
      json
      references {
        ... on Asset {
          url
          width
          height
        }
        ... on Page {
          id
          title
        }
      }
    }
  }
}

Now we should see in the response we get a little bit more about our Page entry:

{
  "data": {
    "page": {
      "content": {
        "json": {
          "children": [
            {
              "type": "paragraph",
              "children": [
                {
                  "text": "Did you know you can embed "
                },
                {
                  "type": "link",
                  "nodeId": "ckz5njfa8ij7m0b05xxqd1ap2",
                  "children": [
                    {
                      "text": "link"
                    }
                  ],
                  "nodeType": "Page"
                },
                {
                  "text": "?"
                }
              ]
            }
          ]
        },
        "references": [
          {
            "id": "ckz5njfa8ij7m0b05xxqd1ap2",
            "title": "Creating pages"
          }
        ]
      }
    }
  }
}

Now if we want to embed a Block entry, we can select this from the Embed dropdown. Block embeds appear in the AST as a root node, so they won't be embedded inside of a paragraph for example.

Finally we can embed an Inline entry which invokes the same behavior as above to select an entry, but will appear inside the AST of the child node. For example, inside the paragraph.

Here's what the final Rich Text editor looks like with these 3 types of embeds added:

Now with all of this added you can query for the content and references to then render on your site. We have several libraries that will help transform the AST to HTML.

• Rich Text HTML Renderer
• Rich Text React Renderer

We also have some guides on working with the above libraries and your frontend frameworks:

• Working with Rich Text & React
• Working with Rich Text & Svelte
• Working with Rich Text & Vue

Hope this has given you a quick look at how you can use Rich Text Embeds to bring a whole new dimension to your content by embedding other content entries.

If you'd like to see a project using embeds you'll want to check out our Docs Starter. You can see below we use the Rich Text React Renderer to show assets, and links to other pages (as block embeds):