https://github.com/flayks/sanity-plugin-references
See which documents reference the current document in your Sanity Studio.
https://github.com/flayks/sanity-plugin-references
reference referencedby references sanity sanity-plugin sanity-studio
Last synced: 1 day ago
JSON representation
See which documents reference the current document in your Sanity Studio.
- Host: GitHub
- URL: https://github.com/flayks/sanity-plugin-references
- Owner: flayks
- License: mit
- Created: 2026-01-05T04:14:50.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-06-11T09:39:59.000Z (25 days ago)
- Last Synced: 2026-06-25T11:28:24.093Z (11 days ago)
- Topics: reference, referencedby, references, sanity, sanity-plugin, sanity-studio
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/sanity-plugin-references
- Size: 350 KB
- Stars: 7
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
🔗 References Plugin for Sanity 🔗
See which documents reference the current document in your Sanity Studio.
Displays a badge with the reference count and a custom pane with the full list.
## Features
- **Reference Badge**: Shows count of documents referencing the current document
- **References Tab**: Lists all referencing documents with:
- 🔍 **Search** by title or document type
- ⬇️ **Sorting** by updated date, type, or title (ascending/descending)
- 📊 **Live Count** of filtered vs total documents
- 🚀 **Click to Navigate** to any referencing document
## Installation
```sh
# npm
npm i sanity-plugin-references
# yarn
yarn add sanity-plugin-references
# pnpm
pnpm add sanity-plugin-references
# bun
bun add sanity-plugin-references
```
## Usage
### Basic Setup
```ts
import { defineConfig } from 'sanity'
import { references } from 'sanity-plugin-references'
export default defineConfig({
plugins: [references()],
})
```
This adds a **reference count badge** to all documents showing how many other documents reference them.
### Adding the References Tab
Add a full References tab with search, filters, and sorting:
```ts
import { structureTool } from 'sanity/structure'
import { references, referencesView } from 'sanity-plugin-references'
export default defineConfig({
plugins: [
references(),
structureTool({
defaultDocumentNode: (S) => S.document().views([
S.view.form(),
referencesView(S),
]),
}),
],
})
```
### Options
**Exclude document types** from showing the badge:
```ts
references({
exclude: ['media.tag', 'sanity.imageAsset'],
})
```
**Customize the tab** title or icon:
```ts
referencesView(S, { title: 'Incoming Links', icon: SomeIcon })
```
**Show tab only for specific types** by checking `schemaType` in `defaultDocumentNode`.
## API
### `references(config?)`
Main plugin function. Adds reference badges to all documents.
- `exclude?: string[]` - Document types to exclude from showing the badge
### `referencesView(S, options?)`
Creates a References view for Structure Builder.
- `title?: string` - Tab title (default: `'References'`)
- `icon?: ComponentType` - Tab icon (default: `LinkIcon`)
### Components
- **`ReferencesPane`** - Raw component for `S.view.component()` (use `referencesView()` instead)
- **`ReferencesBadge`** - Badge component (automatically included via `references()` plugin)
## License
[MIT](LICENSE) © Félix Péault (Flayks)
## Develop & test
This plugin uses [@sanity/plugin-kit](https://github.com/sanity-io/plugin-kit)
with default configuration for build & watch scripts.
See [Testing a plugin in Sanity Studio](https://github.com/sanity-io/plugin-kit#testing-a-plugin-in-sanity-studio)
on how to run this plugin with hotreload in the studio.