Frequently Asked Questions

Rich Text Field: Features & Capabilities

What is the Rich Text field in Hygraph?

The Rich Text field in Hygraph is an advanced string field that allows you to store and manage complex content, such as formatted text, headings, links, tables, images, and lists. It supports multiple output formats, including raw AST, HTML, Markdown, text, and JSON (when embeds are enabled), making it highly flexible for various content delivery needs. [Source]

What output formats does the Rich Text field support?

The Rich Text field supports the following output formats by default: raw (AST), HTML, Markdown, and text. When Rich Text Embeds are enabled, it also supports JSON. This allows developers to choose the most suitable format for their frontend or integration needs. [Source]

How does the Rich Text field handle embeds and assets?

When Rich Text Embeds are enabled, you can embed assets and other models inside Rich Text as block, inline, or link embeds. The API will generate additional types, such as PostContentRichText and PostContentRichTextEmbeddedTypes, allowing you to query embedded references and asset fields directly. This enables rich, interactive content experiences. [Source]

What are the main use cases for each Rich Text output format?

[Source]

How can I customize the display of Rich Text content?

You can use the JSON representation of the Rich Text field to manipulate and customize how content is rendered on your frontend. Hygraph provides tools like the Rich Text HTML renderer and a React version to help you implement custom display logic. For styling, you can follow tutorials such as Styling Rich Text with TailwindCSS. [Source]

What developer resources are available for working with the Rich Text field?

Hygraph offers extensive documentation and guides for the Rich Text field, including a feature walkthrough, tutorials on styling with TailwindCSS, and a React Rich Text Renderer. You can also find API references and code examples in the official documentation. [Source]

Technical Details & Integration

How do I enable Rich Text Embeds in Hygraph?

To enable Rich Text Embeds, you need to configure the field options in your model settings. Once enabled, the Rich Text field will include a JSON output and allow you to embed assets and other models. Detailed instructions are available in the field configuration documentation. [Source]

What is the structure of the Rich Text field type in the API?

The Rich Text field type in the API typically includes the following fields: raw (RichTextAST), html (String), markdown (String), text (String), and json (RichTextAST, available when embeds are enabled). When using embeds, additional types for references are generated. [Source]

How can I programmatically create content entries with Rich Text?

If you are programmatically creating content entries with Rich Text, you should use the @graphcms/html-to-slate-ast package to convert HTML to the required Slate AST format. [Source]

What is the role of the references field in Rich Text embeds?

The references field in Rich Text embeds is a union relation to the types you embedded (e.g., Asset). When querying JSON, you can use the references field to retrieve asset URLs, transformations, and other asset fields. [Source]

General Hygraph Platform & Support

What integrations does Hygraph offer?

Hygraph supports a wide range of integrations, including hosting and deployment (Netlify, Vercel), eCommerce (BigCommerce, Shopify), localization (Lokalise, Crowdin), digital asset management (Cloudinary, AWS S3), personalization (Ninetailed), and more. For a full list, visit the Hygraph Integrations page. [Source]

Where can I find more information about Hygraph's API and SDKs?

You can access comprehensive API references and SDK documentation on the Hygraph API Reference page. This includes details on the Content API, Management SDK, and developer tools. [Source]

What support resources are available for Hygraph users?

Hygraph provides 24/7 support via chat, email, and phone. Enterprise customers receive dedicated onboarding and expert guidance. All users have access to detailed documentation, video tutorials, and a community Slack channel. [Source]

Security & Compliance

How does Hygraph ensure security and compliance for content fields like Rich Text?

Hygraph ensures enterprise-grade security and compliance with certifications such as SOC 2 Type 2, ISO 27001, and GDPR compliance. Features include SSO integrations, audit logs, encryption at rest and in transit, and sandbox environments to protect sensitive data. [Source]

Performance & Business Impact

How does Hygraph optimize content delivery performance?

Hygraph emphasizes optimized content delivery performance, which directly impacts user experience, engagement, and search engine rankings. Rapid content distribution and responsiveness help reduce bounce rates and increase conversions. [Source]

Help teams manage content creation and approval in a clear and structured way
Hygraph
Docs

#Rich Text field

#Overview

The RichText field type is an advanced String field that returns your content in 4 different formats by default: raw, HTML, markdown, and text. JSON is also available when embeds are enabled.

The Rich Text field renders an advanced textarea with tools to add headings, links, tables, images, lists, etc.

When a Rich Text field is added to your model, it will automatically generate the following types:

type RichText {
raw: RichTextAST!
html: String!
markdown: String!
text: String!
json: RichTextAST!
}

#Rich Text data

Let's talk about Rich Text data in more detail.

  • Raw: raw AST (Slate Nodes) offers complete control over how nodes are presented to the user.

  • JSON: JSON representations of RTE allows as much control as raw does, but offers the possibility of creating embeds.

  • HTML: HTML can be used with a Rich Text renderer for customization purposes. While rendering the HTML of your rich text is simple, it doesn't offer great customization.

  • Markdown: Markdown - like HTML - can be used for customization. While markdown is easier to read and write - specially for users without a technical background - it's not as expressive as HTML. To present markdown on a page, you'll need a markdown parser that will convert markdown to HTML.

  • Text: text is mostly used for excerpts, as links, images, and even line breaks are removed.

#Use Cases

  • Raw: Use raw when you want to control the rendered output using our render libraries.
  • JSON: Use JSON for the same as raw but when you also need embeds.
  • HTML / Markdown: Use these when you need to make customizations and want to insert pre-built HTML or markdown into an app.
  • Text: Use text when you want to provide the text as data to a script, such as making full-text search.

#Examples

This section takes a simple Rich Text piece with a title, a paragraph, a link, and bold text, and offers its JSON, HTML, Markdown, and Text representations.

#Rich Text embeds

For example, we can query all of those on our RichText field type content:

#Embed assets

You can also embed Assets and other models inside Rich Text as block, inline or link embeds.

Rich Text Asset Embeds UIRich Text Asset Embeds UI

#Rich Text embeds & API types

With Rich Text Embeds enabled, your API will have some new types added. The name of your field will be now a type appended by RichText, and RichTextEmbeddedTypes inside your schema.

For example, if you had the model Post and field content, the types generates would be PostContentRichText, and PostContentRichTextEmbeddedTypes respectively.

The PostContentRichText type will look like the following:

type RichText {
json: RichTextAST!
html: String!
markdown: String!
text: String!
references: [PostContentRichTextEmbeddedTypes!]!
}

The references field will be a union relation to the types you embedded, for example Asset.

You should use the references field when querying JSON to get the URL (with any transformations, handle, or any of the Asset fields.

The HTML response will return gcms-embed-type and gcms-embed-id data attributes for the embedded types. A block embed is returned as div and an inline embed as span with a data-gcms-embed-inline attribute. A link embed is returned as an a-tag with a data-gcms-embed-id and data-gcms-embed-type attribute.

Hygraph uses Slate 0.5 for RichTextAST.

#Use JSON representation of RTE for customization

You can work with the Rich Text field to take the data that the editors put in Hygraph, and manipulate it for display in the front end.

The following example shows data available on a blog post, with the Rich Text content in HTML and markdown:

Hygraph automatically serializes the content into HTML and/or markdown that the front end can simply display. This does not allow customization.

Instead of these two things, you can get the JSON representation, which will display as JSON AST in a tree with nested levels.

As you can see in the results tab of the above query, this breaks up the initial data into a JSON representation that a renderer can understand.

This allows you to take that data and manipulate it in order to override any default renderer or add renderers for custom elements, creating a custom display logic for your front end.

You will do this by creating an HTML element containing the manipulated data, which will then be rendered via the astToHtmlString method that's available on our Rich Text HTML renderer. We also have a React version of this.

By styling your Rich Text fields, you can either customize how your Rich Text will display throughout your website, or even have multiple types of Rich Text fields that do different things.

#Resources