v6.2.0

Minor Changes

• #309 575c9b4 Thanks @stipsan! - TypeGen-aware Portable Text components

  <PortableText> now infers the shape of every component handler from the value prop. When you pass a value typed by Sanity TypeGen, components.types, components.marks, components.block, components.list, and components.listItem all receive precise value props for the exact content the query returned.

  Three new utility types ship with this feature:

  • InferComponents<T> - same inference as the inline components prop, for hoisting components out of JSX.
  • InferStrictComponents<T> - strict variant that requires a handler for every inferred custom type, mark, block style, and list style, and rejects handlers that aren't in the schema (and therefore not visible to TypeGen).
  • InferValue<T> - derives a Portable Text array value type from any TypeGen query result type, useful for re-usable wrapper components.

  Schema

  Every example below assumes the same sanity.config.ts:

  // sanity.config.ts
  import {
    defineArrayMember,
    defineConfig,
    defineField,
    defineType,
  } from "sanity";
  
  export default defineConfig({
    name: "default",
    projectId: "abc123",
    dataset: "production",
    schema: {
      types: [
        defineType({
          name: "post",
          type: "document",
          fields: [
            defineField({ name: "title", type: "string" }),
            defineField({
              name: "content",
              type: "array",
              of: [
                defineArrayMember({ type: "block" }),
                defineArrayMember({
                  type: "image",
                  options: { hotspot: true },
                  fields: [defineField({ name: "alt", type: "string" })],
                }),
              ],
            }),
          ],
        }),
      ],
    },
  });

  Before: hand-typing handlers

  Previously, every handler had to be typed by hand to mirror the generated query shape:

  // app/[slug]/page.tsx
  import { createClient } from "@sanity/client";
  import { createImageUrlBuilder } from "@sanity/image-url";
  import { PortableText } from "@portabletext/react";
  import { defineQuery } from "groq";
  
  const client = createClient({
    projectId: "abc123",
    dataset: "production",
    useCdn: true,
    apiVersion: "2026-05-04",
  });
  const builder = createImageUrlBuilder(client);
  
  export default async function Page({ slug }: { slug: string }) {
    const query = defineQuery(
      `*[_type == "post" && slug.current == $slug][0]{title,content}`
    );
    const data = await client.fetch(query, { slug });
  
    if (!data) return notFound();
  
    return (
      <article>
        <h1>{data.title}</h1>
        <PortableText
          components={{
            types: {
              image: ({
                value,
              }: {
                value: {
                  asset?: {
                    _ref: string;
                    _type: "reference";
                    _weak?: boolean;
                  };
                  hotspot?: {
                    _type: "sanity.imageHotspot";
                    x?: number;
                    y?: number;
                    height?: number;
                    width?: number;
                  };
                  crop?: {
                    _type: "sanity.imageCrop";
                    top?: number;
                    bottom?: number;
                    left?: number;
                    right?: number;
                  };
                  alt?: string;
                  _type: "image";
                  _key: string;
                };
              }) => (
                <img src={builder.image(value).url()} alt={value.alt || ""} />
              ),
            },
          }}
          value={data.content}
        />
      </article>
    );
  }

  After: automatic inference

  Now the same handler is fully typed straight from data.content:

  // app/[slug]/page.tsx
  import { createClient } from "@sanity/client";
  import { createImageUrlBuilder } from "@sanity/image-url";
  import { PortableText } from "@portabletext/react";
  import { defineQuery } from "groq";
  
  const client = createClient({
    projectId: "abc123",
    dataset: "production",
    useCdn: true,
    apiVersion: "2026-05-04",
  });
  const builder = createImageUrlBuilder(client);
  
  export default async function Page({ slug }: { slug: string }) {
    const query = defineQuery(
      `*[_type == "post" && slug.current == $slug][0]{title,content}`
    );
    const data = await client.fetch(query, { slug });
  
    if (!data) return notFound();
  
    return (
      <article>
        <h1>{data.title}</h1>
        <PortableText
          components={{
            types: {
              // value is fully typed from the query result, no annotation needed
              image: ({ value }) => (
                <img src={builder.image(value).url()} alt={value.alt || ""} />
              ),
            },
          }}
          value={data.content}
        />
      </article>
    );
  }

  InferComponents: hoisting components without losing inference

  Move the components map out of JSX and keep the same inferred handler types:

  // app/[slug]/page.tsx
  import { createClient } from "@sanity/client";
  import { createImageUrlBuilder } from "@sanity/image-url";
  import { PortableText, type InferComponents } from "@portabletext/react";
  import { defineQuery } from "groq";
  
  const client = createClient({
    projectId: "abc123",
    dataset: "production",
    useCdn: true,
    apiVersion: "2026-05-04",
  });
  const builder = createImageUrlBuilder(client);
  
  export default async function Page({ slug }: { slug: string }) {
    const query = defineQuery(
      `*[_type == "post" && slug.current == $slug][0]{title,content}`
    );
    const data = await client.fetch(query, { slug });
  
    if (!data) return notFound();
  
    const components = {
      types: {
        image: ({ value }) => (
          <img src={builder.image(value).url()} alt={value.alt || ""} />
        ),
      },
    } satisfies InferComponents<typeof data.content>;
  
    return (
      <article>
        <h1>{data.title}</h1>
        <PortableText components={components} value={data.content} />
      </article>
    );
  }

  InferStrictComponents + InferValue: a strict, re-usable wrapper

  InferValue<SanityQueries[keyof SanityQueries]> collects every Portable Text item shape from every registered TypeGen query into an array value type, and InferStrictComponents requires a handler for each of them. Together they're perfect for a single CustomPortableText you reuse across the app:

  // app/[slug]/page.tsx
  import { createClient, type SanityQueries } from "@sanity/client";
  import { createImageUrlBuilder } from "@sanity/image-url";
  import {
    PortableText,
    type InferStrictComponents,
    type InferValue,
  } from "@portabletext/react";
  import { defineQuery } from "groq";
  
  const client = createClient({
    projectId: "abc123",
    dataset: "production",
    useCdn: true,
    apiVersion: "2026-05-04",
  });
  const builder = createImageUrlBuilder(client);
  
  // Array value type for every Portable Text item shape across all registered queries.
  type PortableTextValue = InferValue<SanityQueries[keyof SanityQueries]>;
  
  function CustomPortableText({ value }: { value: PortableTextValue }) {
    const components = {
      types: {
        image: ({ value }) => (
          <img src={builder.image(value).url()} alt={value.alt || ""} />
        ),
      },
    } satisfies InferStrictComponents<PortableTextValue>;
    //   ^ TypeScript errors when the schema gains a custom type, mark, or list
    //     style without a matching handler defined here
  
    return <PortableText components={components} value={value} />;
  }
  
  export default async function Page({ slug }: { slug: string }) {
    const query = defineQuery(
      `*[_type == "post" && slug.current == $slug][0]{title,content}`
    );
    const data = await client.fetch(query, { slug });
  
    if (!data) return notFound();
  
    return (
      <article>
        <h1>{data.title}</h1>
        {Array.isArray(data.content) && (
          <CustomPortableText value={data.content} />
        )}
      </article>
    );
  }

v6.1.0

Minor Changes

• #306 ad886e6 Thanks @copilot-swe-agent! - The value prop now accepts null | undefined, and handles it appropriately, to reduce friction when using <PortableText> with Sanity TypeGen

v6.0.3

Patch Changes

• #293 cec15e4 Thanks @renovate! - fix(deps): update dependency @portabletext/toolkit to ^5.0.2

• #294 535636c Thanks @renovate! - fix(deps): update dependency @portabletext/types to ^4.0.2

v6.0.2

Patch Changes

• #283 54d44dc Thanks @renovate! - fix(deps): update dependency @portabletext/toolkit to ^5.0.1

v6.0.1

Patch Changes

• #281 a684e18 Thanks @renovate! - fix(deps): update dependency @portabletext/types to ^4.0.1

v6.0.0

Major Changes

• #262 7fb298b Thanks @renovate! - fix(deps): update dependency @portabletext/types to v4

Patch Changes

• #266 2877ea0 Thanks @renovate! - fix(deps): update dependency @portabletext/toolkit to v5

v5.0.0

Major Changes

• #241 4297499 Thanks @stipsan! - CJS exports removed

• f8901ea Thanks @stipsan! - Support for node versions older than v20.19 dropped

• #246 ecbb6b7 Thanks @renovate! - fix(deps): update dependency @portabletext/toolkit to v4

• #247 4efd54e Thanks @renovate! - fix(deps): update dependency @portabletext/types to v3

v4.0.3

Patch Changes

• #232 a5faf34 Thanks @renovate! - fix(deps): update dependency @portabletext/toolkit to ^3.0.1

v4.0.2

Patch Changes

• #167 cbdfe8d Thanks @AidanLaycock! - Update Readme to include TS imports

v4.0.1

Patch Changes

• #222 66beabe Thanks @stipsan! - allow react 18.2