feat(personalization): add field-level personalization

[stipsan]

Ports sanity-io/sanity-plugin-personalization#38 into the monorepo.

Original author: @jjburbridge (credited via the author: directive in the changeset and as the git commit author).

Walkthrough

Field-level personalization on the Tagline field: activate via the people icon, add a segment, and "Copy default" to seed the value.

field_level_personalization_demo.mp4

Segments section with Add Enterprise / Small Business / Individual buttons
Copy default populates the segment value

What this adds

• fieldLevelPersonalization plugin export — segment-based field personalization (the personalization counterpart to fieldLevelExperiments). Segments can be provided as a static array, fetched from an external API, or stored as Sanity documents (async resolver receives the client).
• Component reorganization — experiment components moved into src/components/experiment/ and the new personalization components live in src/components/personalization/, each with a barrel index.ts. The shared array item component is renamed ExperimentItem → ArrayItem.
• Field groups — experiment/personalization object types now declare default / experiments (or personalization) / all-fields groups, and a clearChildrenGroups helper clears nested group state so fields render cleanly inside arrays and modals.
• Type rename — FieldPluginConfig is renamed to ExperimentFieldPluginConfig, with a deprecated FieldPluginConfig type alias kept for compatibility. New PersonalizationFieldPluginConfig, PersonalizationContextProps, and PersonalizationArrayInputProps types are added.
• Test-studio example — the existing personalization example now also wires fieldLevelPersonalization with sample segments (Enterprise / Small Business / Individual).

Not ported: the upstream CHANGELOG.md / package.json version bumps from semantic-release (the monorepo uses changesets — a minor changeset is included instead).

Review feedback addressed

• Guard nested children before clearing field groups
• Fix preview title operator precedence
• Use configured apiVersion in previews
• Avoid "undefined" segment titles; null-safe preview path traversal

Testing

• pnpm format
• pnpm lint (type-aware oxlint) — passes
• pnpm --filter @sanity/personalization-plugin build — passes
• Plugin vitest — passes
• Manual verification in the test studio (see Walkthrough)

_{To show artifacts inline, enable in settings.}

  

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
plugins-studio	Ready	Preview	Aug 3, 2026 11:24am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
plugins-e2e-test-studio	Ignored		Aug 3, 2026 11:24am

[changeset-bot]

🦋 Changeset detected

Latest commit: 2fc0185

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
sanity-plugin-cloudinary	Minor
@sanity/personalization-plugin	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

Adds field-level personalization to @sanity/personalization-plugin (ported from sanity-io/sanity-plugin-personalization#38), enabling segment-based per-field overrides alongside the existing field-level experiments functionality.

Changes:

• Introduces new fieldLevelPersonalization plugin export with segment types, inputs, and previews.
• Reorganizes experiment and personalization UI components into src/components/experiment/* and src/components/personalization/*, with shared ArrayItem.
• Updates exported/public types (notably renaming FieldPluginConfig → ExperimentFieldPluginConfig) and wires the new feature into the test-studio example + package exports snapshot.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
plugins/@sanity/personalization-plugin/src/utils/clearChildGroups.ts	Adds helper to clear nested field group state for cleaner rendering in arrays/modals.
plugins/@sanity/personalization-plugin/src/types.ts	Renames experiment config type and adds new personalization config/context/input prop types.
plugins/@sanity/personalization-plugin/src/index.ts	Exports fieldLevelPersonalization from the package entrypoint.
plugins/@sanity/personalization-plugin/src/index.test.ts	Updates package-exports snapshot to include fieldLevelPersonalization.
plugins/@sanity/personalization-plugin/src/fieldPersonalization.tsx	Implements the new field-level personalization plugin (schema + form provider wiring).
plugins/@sanity/personalization-plugin/src/fieldExperiments.tsx	Refactors to use reorganized experiment components and adds field groups support.
plugins/@sanity/personalization-plugin/src/components/Select.tsx	Updates SelectOption import to the new experiment component location.
plugins/@sanity/personalization-plugin/src/components/personalization/SegmentPreview.tsx	Adds segment item preview rendering (including reference/image handling).
plugins/@sanity/personalization-plugin/src/components/personalization/SegmentInput.tsx	Adds “Copy default” functionality for segment values.
plugins/@sanity/personalization-plugin/src/components/personalization/index.ts	Adds personalization components barrel exports.
plugins/@sanity/personalization-plugin/src/components/personalization/Field.tsx	Adds field action to toggle/remove personalization and clears nested groups.
plugins/@sanity/personalization-plugin/src/components/personalization/Context.tsx	Adds personalization provider/context that resolves segments (sync/async).
plugins/@sanity/personalization-plugin/src/components/personalization/Array.tsx	Adds segment “Add …” buttons to append segment entries into the array.
plugins/@sanity/personalization-plugin/src/components/experiment/VariantPreview.tsx	Updates imports after experiment component reorganization.
plugins/@sanity/personalization-plugin/src/components/experiment/VariantInput.tsx	Adds “Copy default” functionality for variant values.
plugins/@sanity/personalization-plugin/src/components/experiment/Input.tsx	Renames experiment input component and updates imports after reorg.
plugins/@sanity/personalization-plugin/src/components/experiment/index.ts	Adds experiment components barrel exports.
plugins/@sanity/personalization-plugin/src/components/experiment/Field.tsx	Renames/updates field component and clears nested groups before rendering.
plugins/@sanity/personalization-plugin/src/components/experiment/Context.tsx	Updates imports/types for the renamed experiment config type.
plugins/@sanity/personalization-plugin/src/components/experiment/Array.tsx	Updates imports after experiment component reorganization.
plugins/@sanity/personalization-plugin/src/components/ArrayItem.tsx	Renames shared array item component (ExperimentItem → ArrayItem).
dev/test-studio/src/personalization/index.tsx	Updates test studio example to include fieldLevelPersonalization with sample segments.
.changeset/field-level-personalization.md	Adds a minor changeset with author credit and summary of the new export + type rename.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

✅ E2E Tests

🟢 24 passed • view full report • view run

Studio: https://plugins-e2e-test-studio-9btrfm1o2.sanity.dev

Datasets: pr-1226-chromium-30809351975, pr-1226-firefox-30809351975

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (7)

plugins/@sanity/personalization-plugin/src/components/personalization/SegmentPreview.tsx:19

• useClient is hard-coded to apiVersion 2025-01-01, which ignores the plugin's configurable apiVersion (available in PersonalizationContext). This makes the preview behavior diverge from the rest of the plugin and from user expectations when they set apiVersion.

  const {segments, apiVersion} = usePersonalizationContext()
  const client = useClient({apiVersion})

plugins/@sanity/personalization-plugin/src/components/personalization/SegmentPreview.tsx:46

• The reduce((acc, index) => acc[index], doc) will throw if any intermediate path segment is missing (because acc becomes undefined and the next iteration reads acc[index]). Use optional chaining in the reducer so missing paths resolve to undefined instead of crashing the preview.

        Object.keys(previewFields).forEach((key) => {
          const valueKey = referenceType?.preview?.select?.[key]
          selectFields[key] =
            valueKey && doc
              ? valueKey.split('.').reduce((acc: any, index) => {

plugins/@sanity/personalization-plugin/src/utils/clearChildGroups.ts:24

• children.props.children is spread without being validated. If children.props.children is undefined (or not an element-like object), ...children.props.children will throw at runtime. Add a guard for the nested child before spreading and reuse a nestedChild variable when building the updated props tree.

    !('props' in innerChild)
  ) {
    return props
  }

plugins/@sanity/personalization-plugin/src/components/personalization/SegmentPreview.tsx:29

• setTitle(${selectedSegment?.label}) will set the literal string "undefined" when no segment is selected. Assign the label directly so the state remains undefined in that case.

      setTitle(selectedSegment?.label)

plugins/@sanity/personalization-plugin/src/fieldPersonalization.tsx:246

• PersonalizationProvider is called like a regular function. Since it uses React hooks, this violates the Rules of Hooks and can break if the hasPersonalization condition ever changes between renders. Render it as a component instead.

              personalizationFieldPluginConfig: {

plugins/@sanity/personalization-plugin/src/types.ts:24

• The exported FieldPluginConfig type was renamed/removed. Removing an exported type is a breaking change for TypeScript consumers; adding a deprecated alias keeps existing users compiling while still introducing the clearer ExperimentFieldPluginConfig name (and better matches the minor bump in the changeset).

export type ExperimentFieldPluginConfig = {
  fields: (string | FieldDefinition)[]
  experiments: ExperimentType[] | ((client: SanityClient) => Promise<ExperimentType[]>)
  apiVersion?: string
  experimentNameOverride?: string

plugins/@sanity/personalization-plugin/src/fieldPersonalization.tsx:214

• Plugin name contains a misspelling (personalistaion). This can make plugin identification/debugging inconsistent (and differs from the package name).

This issue also appears on line 246 of the same file.

      personalizationNameOverride,

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	30.46%	5001 / 16413
🔵	Statements	30.18%	5258 / 17418
🔵	Functions	26.11%	1274 / 4879
🔵	Branches	21.58%	2485 / 11510

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
plugins/@sanity/personalization-plugin/src/fieldExperiments.tsx	9.3%	0%	0%	9.3%	38-160, 177-219, 230-242, 248-297
plugins/@sanity/personalization-plugin/src/fieldPersonalization.tsx	10.25%	0%	0%	10.25%	35-131, 146-180, 190-199, 206-252
plugins/@sanity/personalization-plugin/src/index.ts	0%	0%	0%	0%
plugins/@sanity/personalization-plugin/src/types.ts	0%	0%	0%	0%
plugins/@sanity/personalization-plugin/src/components/Select.tsx	20%	0%	0%	20%	22-37
plugins/@sanity/personalization-plugin/src/components/experiment/index.ts	0%	0%	0%	0%
plugins/@sanity/personalization-plugin/src/components/personalization/Array.tsx	7.69%	0%	0%	8.33%	9-51
plugins/@sanity/personalization-plugin/src/components/personalization/Context.tsx	15.38%	0%	0%	15.38%	26-61
plugins/@sanity/personalization-plugin/src/components/personalization/Field.tsx	12.9%	0%	0%	12.9%	23-35, 46-59, 73-96, 105-133
plugins/@sanity/personalization-plugin/src/components/personalization/SegmentInput.tsx	14.28%	100%	0%	14.28%	5-15
plugins/@sanity/personalization-plugin/src/components/personalization/SegmentPreview.tsx	2.7%	0%	0%	2.85%	15-69
plugins/@sanity/personalization-plugin/src/components/personalization/index.ts	0%	0%	0%	0%
plugins/@sanity/personalization-plugin/src/utils/clearChildGroups.ts	12.5%	0%	0%	12.5%	10-41

Generated in workflow #8452 for commit 2fc0185 by the Vitest Coverage Report Action

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e4ba4de. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (3)

plugins/@sanity/personalization-plugin/src/components/experiment/Input.tsx:14

• Importing ExperimentType from ../.. couples this component to the package barrel (src/index.ts) and risks circular type dependencies as exports evolve. Import the type directly from src/types instead.
  plugins/@sanity/personalization-plugin/src/fieldPersonalization.tsx:220
• Plugin name string contains a typo ("personalistaion"), which makes the plugin identifier harder to search for and inconsistent with the package name.

      name: 'sanity-personalistaion-plugin-field-level-personalization',

plugins/@sanity/personalization-plugin/src/fieldPersonalization.tsx:210

• segmentId / segmentArrayName are always derived from segmentNameOverride, so any explicit segmentId/segmentArrayName passed in the plugin config is ignored. If these fields are part of the public config type, they should be respected when provided (and only derived as a default).

    const segmentArrayName = `${segmentNameOverride}s`
    const segmentId = `${segmentNameOverride}Id`

[Copilot]

Pull request overview

Copilot reviewed 23 out of 24 changed files in this pull request and generated no new comments.

Suppressed comments (5)

plugins/@sanity/personalization-plugin/src/fieldPersonalization.tsx:252

• PersonalizationProvider uses hooks, but it’s being invoked as a plain function (PersonalizationProvider(providerProps)). This makes its hooks run inside the parent input component and only when hasPersonalization is true, which can violate the Rules of Hooks and break if the condition ever changes. Render it as a component instead.

            return <PersonalizationProvider {...providerProps} />

plugins/@sanity/personalization-plugin/src/components/experiment/VariantPreview.tsx:40

• VariantPreview doesn’t clear media/subtitle when value changes between types (e.g. reference → string/image). This can leave stale preview UI from the previous value. Clear state up front in the effect before branching on value.
  plugins/@sanity/personalization-plugin/src/components/personalization/SegmentPreview.tsx:32
• SegmentPreview doesn’t clear media/subtitle when value changes between types (e.g. reference → string/image). This can leave stale preview UI from the previous value. Clear state up front in the effect before branching on value.

      setTitle(selectedSegment?.label)
      if (typeof value === 'string') {
        return setSubtitle(value)
      }

plugins/@sanity/personalization-plugin/src/components/personalization/SegmentPreview.tsx:60

• The effect dependencies don’t include segment. If the selected segment changes but the label stays the same (or selectedSegment resolves to another item with the same label), the effect won’t rerun and the preview can become stale.

  }, [value, client, selectedSegment?.label, props.schemaType])

plugins/@sanity/personalization-plugin/src/components/personalization/SegmentInput.tsx:9

• useFormValue can return undefined when the default field is empty/unset. Passing undefined into set(...) produces an invalid JSON patch (and can crash when patches are serialized). Guard this case and unset(['value']) (or no-op) instead.

  const handleClick = () => {
    props.onChange(set(defaultValue, ['value']))
  }

[Copilot]

Pull request overview

Copilot reviewed 23 out of 24 changed files in this pull request and generated no new comments.

Suppressed comments (6)

plugins/@sanity/personalization-plugin/src/components/personalization/SegmentPreview.tsx:38

• This reference preview path can throw when the value field isn’t actually a reference type (or the schema shape differs): referenceField can be undefined, but referenceField.to.find(...) is called unconditionally.

        const type = props.schemaType as ObjectSchemaType
        const valueField = type.fields.find((field) => field.name === 'value') as ObjectSchemaType
        const referenceField = valueField?.type as ReferenceSchemaType
        const referenceType = referenceField.to.find((field) => field.type?.name === doc?._type)

plugins/@sanity/personalization-plugin/src/components/experiment/VariantPreview.tsx:37

• VariantPreview stores media/subtitle in state, but doesn’t clear them when value changes between types (e.g. previously an image, now a string). This can leave stale media or subtitle from a previous value showing in the preview.

This issue also appears on line 53 of the same file.
plugins/@sanity/personalization-plugin/src/components/experiment/VariantPreview.tsx:55

• This branch can still throw before the null-safe reduce: referenceField can be undefined depending on the schema shape, but referenceField.to.find(...) is called unconditionally. This would crash the document form preview for non-reference value fields.
  plugins/@sanity/personalization-plugin/src/fieldPersonalization.tsx:210
• fieldLevelPersonalization computes segmentArrayName/segmentId from segmentNameOverride, but PersonalizationFieldPluginConfig also exposes segmentArrayName and segmentId overrides. As written, user-provided values are silently ignored, which is surprising for API consumers and makes those config fields ineffective.

    const segmentArrayName = `${segmentNameOverride}s`
    const segmentId = `${segmentNameOverride}Id`

plugins/@sanity/personalization-plugin/src/fieldExperiments.tsx:250

• ExperimentFieldPluginConfig exposes experimentId / variantId / variantArrayName overrides, but fieldLevelExperiments always derives these from the *NameOverride values. This makes the override fields ineffective and prevents consumers from aligning with existing schema field names.

  const pluginConfig = {...CONFIG_DEFAULT, ...config}
  const {fields, experimentNameOverride, variantNameOverride} = pluginConfig

plugins/@sanity/personalization-plugin/src/components/personalization/SegmentPreview.tsx:32

• SegmentPreview keeps media/subtitle in state, but doesn’t clear them when value changes between types (e.g. image → string, reference → image). This can leave stale media or subtitle from a previous value showing in the preview.

This issue also appears on line 35 of the same file.

    const getSubtitle = async () => {
      setTitle(selectedSegment?.label)
      if (typeof value === 'string') {
        return setSubtitle(value)
      }