We just launched our new Hygraph Studio in beta. Learn more

Working with Rich Text Embeds

In this post we'll explore working with the Rich Text embed types Link, Inline, and Block.
Jamie Barton

Jamie Barton

Jun 10, 2022
working with rich text embeds in hygraph

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:

Page model

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.

Enable embeds

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

Rich Text Editor

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

Embed Link 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.

Embed Block Entry

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:

Rich Text Editor with Embeds

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.

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

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):

Docs starter preview

Blog Author

Jamie Barton

Jamie Barton

Jamie is a software engineer turned developer advocate. Born and bred in North East England, he loves learning and teaching others through video and written tutorials. Jamie currently publishes Weekly GraphQL Screencasts.

Share with others

Sign up for our newsletter!

Be the first to know about releases and industry news and insights.