@gavinrigs/decap-relation2

A replacement for Decap's relation widget that adds live cross-field filtering, cross-widget uniqueness, and data resolution for previews.

Provides two widgets:

• relation2 — a searchable single/multi select backed by another collection.
• hiddenfetch — no visible UI; fetches a collection, filters it, and publishes the result for previews and dependent fields.

Registering

import CMS from "decap-cms-app";
import { register } from "@gavinrigs/decap-relation2";

register(CMS);

| Option | Default | Purpose | | --- | --- | --- | | relationName | "relation2" | Widget name used in config.yml. | | hiddenFetchName | "hiddenfetch" | Widget name used in config.yml. |

Field configuration

- name: author
  widget: relation2
  collection: authors
  value_field: slug
  display_fields: [name]
  search_fields: [name]

- name: venue
  widget: relation2
  collection: venues
  filter: "{city=='${city}'}"   # re-evaluates live as `city` changes

- name: seat
  widget: relation2
  collection: seats
  unique_key: seating           # values picked by siblings are hidden

- name: cms_template
  widget: hiddenfetch
  collection: templates
  file: post.njk
  resolved_name: cms_template   # defaults to `<name>_resolved`

• filter supports ${fieldName} references to other fields in the entry. Decap does not re-render dependent widgets when a field changes, so relation2 broadcasts each selection and hiddenfetch re-applies its filter immediately.
• unique_key groups widgets that must not select the same value twice.

Preview integration

register() publishes resolved data through the entry-data provider registry in @gavinrigs/decap-plugin-core. Any preview plugin that reads that registry — such as @gavinrigs/decap-nunjucks-preview — picks it up automatically. Neither package imports the other.

Dependencies

• @gavinrigs/decap-plugin-core
• Peer: react, react-select