Structured Text fields

Remix Blog

Words are nice... but code speaks louder. Dive into a fully commented project template, showcasing these techniques (and more) in action.

Remix > Structured Text fields

Rich-text in DatoCMS is stored in Structured Text fields, as it offers many advantages over regular HTML.

There's a lot to be said about Structured Text and the extensibility of it, but for now let's just say that it returns content in a particular JSON format called dast which resembles this example:

1
{
2
  "schema": "dast",
3
  "document": {
4
    "type": "root",
5
    "children": [
6
      {
7
        "type": "heading",
8
        "level": 1,
9
        "children": [
10
          {
11
            "type": "span",
12
            "value": "Hello world!"
13
          }
14
        ]
15
      }
16
    ]
17
  }
18
}

To make it easy to render Structured Text inside your Remix projects, we released a package called react-datocms that exposes a <StructuredText /> component that performs all the tedious work for you.

To take advantage of it, install the react-datocms package if you haven't already:

npm i --save react-datocms

Then, inside your page, make a GraphQL query to fetch a Structured Text field, and feed the result to the data prop of a <StructuredText /> component:

1
import { load } from "~/lib/datocms";
2
import { StructuredText } from "react-datocms";
3
import { useLoaderData } from "remix";
4

5
const HOMEPAGE_QUERY = `query HomePage($limit: IntType) {
6
  posts: allBlogPosts(first: $limit) {
7
    id
8
    title
9
    content {
10
      value
11
    }
12
  }
13
}`;
14

15
export async function loader() {
16
  return load(HOMEPAGE_QUERY, {
17
    variables: { limit: 10 }
18
  });
19
}
20

21
export default function Home() {
22
  const { posts } = useLoaderData();
23

24
  return (
25
    <div>
26
      {posts.map(blogPost => (
27
        <article key={blogPost.id}>
28
          <h6>{blogPost.title}</h6>
29
          <StructuredText data={blogPost.content} />
30
        </article>
31
      ))}
32
    </div>
33
  );
34
}

Rendering special nodes

Other than “regular” formatting nodes — paragraphs, headings, lists, etc. — Structured Text documents can contain three special types of node:

itemLink nodes are just like regular HTML hyperlinks, but point to other records instead of URLs;
inlineItem nodes let you directly embed a reference to a record in-between regular text;
block nodes let you embed a DatoCMS block record in-between regular paragraphs;

If a Structured Text document contains one of these nodes, then we need to change the GraphQL query, so that we also fetch all the records and blocks it references.

As an example, if the field can link to other Blog posts, and can embed blocks of type Image block, then the query should change like this:

1
const HOMEPAGE_QUERY = `query HomePage($limit: IntType) {
2
  posts: allBlogPosts(first: $limit) {
3
    id
4
    title
5
    content {
6
      value
7
      blocks {
8
        ... on RecordInterface {
9
          id
10
          __typename
11
        }
12
        ... on ImageBlockRecord {
13
          image { url alt }
14
        }
15
      }
16
      links {
17
        ... on RecordInterface {
18
          id
19
          __typename
20
        }
21
        ... on BlogPostRecord {
22
          slug
23
          title
24
        }
25
      }
26
    }
27
  }
28
}`;

We also need to tell <StructuredText /> how you want such nodes to be rendered:

1
return (
2
  <StructuredText
3
    data={blogPost.content}
4
    renderInlineRecord={({ record }) => {
5
      switch (record.__typename) {
6
        case "BlogPostRecord":
7
          return <a href={`/blog/${record.slug}`}>{record.title}</a>;
8
        default:
9
          return null;
10
      }
11
    }}
12
    renderLinkToRecord={({ record, children }) => {
13
      switch (record.__typename) {
14
        case "BlogPostRecord":
15
          return <a href={`/blog/${record.slug}`}>{children}</a>;
16
        default:
17
          return null;
18
      }
19
    }}
20
    renderBlock={({ record }) => {
21
      switch (record.__typename) {
22
        case "ImageBlockRecord":
23
          return <img src={record.image.url} alt={record.image.alt} />;
24
        default:
25
          return null;
26
      }
27
    }}
28
  />
29
);