@graphcms/rich-text-react-renderer

中文文档
0.6.2发布于 2024/08/16MITTypeScriptESM + CJS近 30 天下载 2.9万

Hygraph Rich Text React renderer

原始使用文档
文档目录20 节
  1. ⚡ Getting started
  2. 🔥 Usage/Examples
  3. Custom elements
  4. Custom assets
  5. References
  6. Custom embeds
  7. References
  8. Link embeds
  9. Empty elements
  10. TypeScript
  11. Children Type
  12. Custom Embeds/Assets
  13. Examples
  14. Next.js Link component
  15. Next.js Image component
  16. Placeholder images for Next.js Image component
  17. Gatsby Link component
  18. Gatsby Image component
  19. Code blocks with Prism.js
  20. 📝 License

@graphcms/rich-text-react-renderer

Render Rich Text content from Hygraph in React applications.

⚡ Getting started

You can get it on npm or Yarn.

# npm
npm i @graphcms/rich-text-react-renderer

# Yarn
yarn add @graphcms/rich-text-react-renderer

🔥 Usage/Examples

To render the content on your application, you'll need to provide the array of elements returned from the Hygraph API to the RichText component. The content has to be returned in raw (or json) format as the AST representation. For more information on how to query the Rich Text content, check our documentation.

import { RichText } from '@graphcms/rich-text-react-renderer';

const content = {
  children: [
    {
      type: 'paragraph',
      children: [
        {
          bold: true,
          text: 'Hello World!',
        },
      ],
    },
  ],
};

function App() {
  return <RichText content={content} />;
}

The content from the example above will render:

<p>
  <b>Hello world!</b>
</p>

Custom elements

By default, the elements won't have any styling, despite the IFrame, which we designed to be responsive. But if you have, for example, a design system and wants to use your own components with styling, you can pass a renderers prop to the RichText component. Let's see an example:

import { RichText } from '@graphcms/rich-text-react-renderer';

const content = {
  /* ... */
};

function App() {
  return (
    <div>
      <RichText
        content={content}
        renderers={{
          h1: ({ children }) => <h1 className="text-white">{children}</h1>,
          bold: ({ children }) => <strong>{children}</strong>,
        }}
      />
    </div>
  );
}

Below you can check the full list of elements you can customize, alongside the props available for each of them.

  • a
    • children: ReactNode;
    • href: string;
    • className: string;
    • rel: string;
    • id: string;
    • title: string;
    • openInNewTab: boolean;
  • class
    • children: ReactNode;
    • className: string;
  • img
    • src: string;
    • title: string;
    • width: number;
    • height: number;
    • mimeType: ImageMimeTypes;
    • altText: string;
  • video
    • src: string;
    • title: string;
    • width: number;
    • height: number;
  • iframe
    • url: string;
    • width: number;
    • height: number;
  • h1
    • children: ReactNode;
  • h2
    • children: ReactNode;
  • h3
    • children: ReactNode;
  • h4
    • children: ReactNode;
  • h5
    • children: ReactNode;
  • h6
    • children: ReactNode;
  • p
    • children: ReactNode;
  • ul
    • children: ReactNode;
  • ol
    • children: ReactNode;
  • li
    • children: ReactNode;
  • table
    • children: ReactNode;
  • table_head
    • children: ReactNode;
  • table_header_cell
    • children: ReactNode;
  • table_body
    • children: ReactNode;
  • table_row
    • children: ReactNode;
  • table_cell
    • children: ReactNode;
  • blockquote
    • children: ReactNode;
  • bold
    • children: ReactNode;
  • italic
    • children: ReactNode;
  • underline
    • children: ReactNode;
  • code
    • children: ReactNode;
  • code_block
    • children: ReactNode;

Custom assets

The Rich Text field allows you to embed assets. By default, we render images, videos and audios out of the box. However, you can define custom components for each mime type group. Below you can see the complete list of mimeType groups.

  • audio
  • application
  • image
  • video
  • font
  • model
  • text

We don't have components to render fonts, models, text and application files, but you can write your own depending on your needs and project. If you need, you can also have a custom renderer for a specific mimeType. Here's an example:

import { RichText } from '@graphcms/rich-text-react-renderer';

const content = [
  {
    type: 'embed',
    nodeId: 'cknjbzowggjo90b91kjisy03a',
    children: [
      {
        text: '',
      },
    ],
    nodeType: 'Asset',
  },
  {
    type: 'embed',
    nodeId: 'ckrus0f14ao760b32mz2dwvgx',
    children: [
      {
        text: '',
      },
    ],
    nodeType: 'Asset',
  },
];

const references = [
  {
    id: 'cknjbzowggjo90b91kjisy03a',
    url: 'https://media.graphassets.com/dsQtt0ARqO28baaXbVy9',
    mimeType: 'image/png',
  },
  {
    id: 'ckrus0f14ao760b32mz2dwvgx',
    url: 'https://media.graphassets.com/7M0lXLdCQfeIDXnT2SVS',
    mimeType: 'video/mp4',
  },
];

function App() {
  return (
    <RichText
      content={content}
      references={references}
      renderers={{
        Asset: {
          video: () => <div>custom VIDEO</div>,
          image: () => <div>custom IMAGE</div>,
          'video/mp4': () => {
            return <div>custom video/mp4 renderer</div>;
          },
        },
      }}
    />
  );
}

As mentioned, you can write renderers for all mimeType groups or to specific mimeType.

References

References are required on the RichText component to render embed assets.

id, mimeType and url are required in your Asset query.

Query example:

{
  articles {
    content {
      json
      references {
        ... on Asset {
          id
          url
          mimeType
        }
      }
    }
  }
}

Custom embeds

Imagine you have an embed Post on your Rich Text field. To render it, you can have a custom renderer. Let's see an example:

import { RichText } from '@graphcms/rich-text-react-renderer';

const content = [
  {
    type: 'embed',
    nodeId: 'custom_post_id',
    children: [
      {
        text: '',
      },
    ],
    nodeType: 'Post',
  },
];

const references = [
  {
    id: 'custom_post_id',
    title: 'Hygraph is awesome :rocket:',
  },
];

function App() {
  return (
    <RichText
      content={content}
      references={references}
      renderers={{
        embed: {
          Post: ({ title, nodeId }) => {
            return (
              <div className="post">
                <h3>{title}</h3>
                <p>{nodeId}</p>
              </div>
            );
          },
        },
      }}
    />
  );
}

References

References are required on the RichText component. You also need to include your model in your query.

  • id is always required in your model query. It won't render if it's not present.
{
  articles {
    content {
      json
      references {
        ... on Asset {
          id
          url
          mimeType
        }
        # Your post query
        ... on Post {
          id # required
          title
          slug
          description
        }
      }
    }
  }
}

The Rich Text Field also supports Link Embeds, which work similarly to normal embeds. Based on the model name, you can have a custom renderer for it. Example:

import { RichText } from '@graphcms/rich-text-react-renderer';

const content = [
  {
    type: 'link',
    nodeId: 'post_id',
    children: [
      {
        text: 'click here',
      },
    ],
    nodeType: 'Post',
  },
];

const references = [
  {
    id: 'post_id',
    slug: 'hygraph-is-awesome',
  },
];

function App() {
  return (
    <RichText
      content={content}
      references={references}
      renderers={{
        link: {
          Post: ({ slug, children }) => {
            return <a href={`/blog/${slug}`}>{children}</a>;
          },
        },
      }}
    />
  );
}

Empty elements

By default, we remove empty headings from the element list to prevent SEO issues. Other elements, such as thead are also removed. You can find the complete list here.

TypeScript

If you are using TypeScript in your project, we recommend installing the @graphcms/rich-text-types package. It contains types for the elements, alongside the props accepted by them. You can use them in your application to create custom components.

Children Type

If you need to type the content from the Rich Text field, you can do so by using the types package. Example:

import { ElementNode } from '@graphcms/rich-text-types';

type Content = {
  content: {
    raw: {
      children: ElementNode[];
    };
  };
};

Custom Embeds/Assets

Depending on your reference query and model, fields may change, which applies to types. To have a better DX using the package, we have EmbedProps and LinkEmbedProps types that you can import from @graphcms/rich-text-types (you may need to install it if you don't have done it already).

In this example, we have seen how to write a renderer for a Post model, but it applies the same way to any other model and Asset on your project.

import { EmbedProps, LinkEmbedProps } from '@graphcms/rich-text-types';

type Post = {
  title: string;
  slug: string;
  description: string;
};

function App() {
  return (
    <RichText
      // ...
      renderers={{
        embed: {
          Post: ({ title, description, slug }: EmbedProps<Post>) => {
            return (
              <div className="post">
                <a href={`/blog/${slug}`}>
                  <h3>{title}</h3>
                  <p>{description}</p>
                </a>
              </div>
            );
          },
        },
        link: {
          Post: ({ slug, children }: LinkEmbedProps<Post>) => {
            return <a href={`/blog/${slug}`}>{children}</a>;
          },
        },
      }}
    />
  );
}

Examples

import Link from 'next/link';
import { RichText } from '@graphcms/rich-text-react-renderer';

const content = {
  /* ... */
};

function App() {
  return (
    <RichText
      content={content}
      renderers={{
        a: ({ children, openInNewTab, href, rel, ...rest }) => {
          if (href.match(/^https?:\/\/|^\/\//i)) {
            return (
              <a
                href={href}
                target={openInNewTab ? '_blank' : '_self'}
                rel={rel || 'noopener noreferrer'}
                {...rest}
              >
                {children}
              </a>
            );
          }

          return (
            <Link href={href}>
              <a {...rest}>{children}</a>
            </Link>
          );
        },
      }}
    />
  );
}

Next.js Image component

import Image from 'next/image';
import { RichText } from '@graphcms/rich-text-react-renderer';

const content = {
  /* ... */
};

function App() {
  return (
    <RichText
      content={content}
      renderers={{
        img: ({ src, altText, height, width }) => (
          <Image
            src={src}
            alt={altText}
            height={height}
            width={width}
            objectFit="cover"
          />
        ),
      }}
    />
  );
}

Since the images are in the Hygraph CDN, you need to specify our domain in the next.config.js file. For more information, check this guide.

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.graphassets.com',
      },
    ],
  },
};

Placeholder images for Next.js Image component

For low quality image placeholders (LQIP) we can use Plaiceholder. Plaiceholder will generate base64 encoded images which we pass to next/image as the blurDataUrl prop. In this example we'll query a rich text field and generate a placeholder image for each embedded asset.

First, install Plaiceholder:

# npm
npm i plaiceholder

# Yarn
yarn add plaiceholder

Note that Plaiceholder uses sharp under the hood, but as next/image ships with it, we don't need to install it separately.

Here's a full blown example for a single blog post page with rich text content.

// [slug.jsx]
import { RichText } from '@graphcms/rich-text-react-renderer';
import { getPlaiceholder } from 'plaiceholder';
import { fetchFromHygraph } from '../../lib/hygraph';
import Image from 'next/image';

// Page template
const SinglePostPage = ({ data }) => {
  const { title, description, content } = data;

  return (
    <>
      {/* ... */}
      <RichText
        content={content.json}
        references={content.references}
        renderers={{
          Asset: {
            image: ({ url, alt, caption, width, height, blurDataUrl }) => {
              return (
                <Image
                  src={url}
                  alt={alt}
                  width={width}
                  height={height}
                  placeholder={blurDataUrl ? 'blur' : 'empty'}
                  blurDataURL={blurDataUrl}
                />
              );
            },
          },
        }}
      />
    </>
  );
};

export const getStaticPaths = async () => {
  // Get your paths here.
};

export const getStaticProps = async context => {
  const data = await fetchFromHygraph({
    // Sample query, adjust to your content structure.
    // Note: 'id' and 'mimeType' are required for custom components.
    query: `
      query ($slug: String!) {
        post(where: { slug: $slug }) {
          slug
          content {
            json
            references {
              ... on Asset {
                id
                mimeType
                url
                alt
                caption
                width
                height
              }
            }
          }
        }
      }
    `,
    variables: {
      slug: context.params?.slug,
    },
    preview: context.preview,
  });

  // Pick images from assets
  const images = data.post.content.references.filter(asset =>
    asset.mimeType.includes('image')
  );

  // Use Plaiceholder to generate placeholder images (LQIP)
  // As a result the images will have a `blurDataUrl` prop with the
  // base64 encoded image.
  await Promise.all(
    images.map(async image => {
      const { base64 } = await getPlaiceholder(image.url);
      image.blurDataUrl = base64;
    })
  );

  return {
    props: {
      data: data.post,
    },
  };
};

export default SinglePostPage;
import { Link } from 'gatsby';
import { RichText } from '@graphcms/rich-text-react-renderer';

const content = {
  /* ... */
};

function App() {
  return (
    <RichText
      content={content}
      renderers={{
        a: ({ children, openInNewTab, href, rel, ...rest }) => {
          if (href.match(/^https?:\/\/|^\/\//i)) {
            return (
              <a
                href={href}
                target={openInNewTab ? '_blank' : '_self'}
                rel={rel || 'noopener noreferrer'}
                {...rest}
              >
                {children}
              </a>
            );
          }

          return (
            <Link to={href} {...rest}>
              {children}
            </Link>
          );
        },
      }}
    />
  );
}

Gatsby Image component

Unfortunately, there's no way to use the Gatsby Image component with this package at the moment. The GatsbyImage component (for dynamic images) fetches the image from a query during build time, which is not possible to accomplish right now. For more information, see hygraph/rich-text#16.

Code blocks with Prism.js

By default, as you may have already realized, the code-blocks rendered by the package don't have any unique styling since we're unopinionated on how it should look on your application. But, if you need, you can create your code block, add a background color for it, add some padding, and adjust based on your needs.

If you want to go one step away, you can also integrate with Prism.js or highlight.js. Below you can see an example using Prism.js:

Note: we still don't support defining a custom language for a code block in the Rich Text field.

import { useEffect } from 'react';
import { RichText } from '@graphcms/rich-text-react-renderer';

import Prism from 'prismjs';
import 'prismjs/plugins/line-numbers/prism-line-numbers';
import 'prismjs/themes/prism-tomorrow.css';
import 'prismjs/plugins/line-numbers/prism-line-numbers.css';

const content = {
  /* ... */
};

function App() {
  useEffect(() => {
    Prism.highlightAll();
  }, []);

  return (
    <RichText
      content={content}
      renderers={{
        code_block: ({ children }) => {
          return (
            <pre className="line-numbers language-none">
              <code>{children}</code>
            </pre>
          );
        },
      }}
    />
  );
}

📝 License

Licensed under the MIT License.


Made with 💜 by Hygraph 👋 join our community!

版本与发布记录

@graphcms/rich-text-react-renderer 共发布 21 个版本,首次发布于 2021/05/12;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.6.2latest2024/08/162 年前
0.6.12022/07/044 年前
0.6.02022/07/024 年前
0.5.02022/04/064 年前
0.4.32022/03/224 年前
0.4.22022/01/134 年前

其他发布通道:canary → 0.1.1-canary.1。

关于 @graphcms/rich-text-react-renderer 的常见问题

@graphcms/rich-text-react-renderer 是什么?

Hygraph Rich Text React renderer

如何安装 @graphcms/rich-text-react-renderer?

在项目目录运行 npm install @graphcms/rich-text-react-renderer,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=16)、react-dom(>=16)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@graphcms/rich-text-react-renderer 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@graphcms/rich-text-react-renderer 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@graphcms/rich-text-react-renderer 可以商用吗?

@graphcms/rich-text-react-renderer 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@graphcms/rich-text-react-renderer 的下载量有多少?

根据 npm 官方下载统计,@graphcms/rich-text-react-renderer 在 2026/10/17 – 2026/11/15 这 30 天内被下载 28,808 次,日均约 960 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@graphcms/rich-text-react-renderer 还在维护吗?

最新版本 0.6.2 发布于 2024/08/16(2 年前);至今共发布 21 个版本,其中过去 12 个月发布了 0 个;首次发布于 2021/05/12。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。