Auto-tag on upload

[einarlove]

Closes #200

Description

Adds the ability to automatically tag assets when they are uploaded through image field. This helps keep the media library organised without relying on users to manually tag assets.

When opening the Media Browser from a field with mediaTags configured, the browser now automatically filters to show only assets that have those tags, making it easier to find relevant assets.

Usage

Add a mediaTags option to any image or file field:

defineField({
  type: 'image',
  name: 'portrait',
  options: {
    hotspot: true,
    mediaTags: ['employee', 'portrait']
  }
})

When a user uploads an image through this field, the asset will automatically be tagged with "employee" and "portrait".

When a user opens the Media Browser from this field, the browser will automatically filter to show only assets tagged with both "employee" and "portrait".

How it works

flowchart TD
    Upload[User uploads asset] --> Wrapper[AutoTagInputWrapper]

    Wrapper --> CheckType{Is image or file field?}
    CheckType -->|No| RenderDefault[Render default input]
    CheckType -->|Yes| CheckTags{Has mediaTags option?}
    CheckTags -->|No| RenderDefault
    CheckTags -->|Yes| WatchChanges[Watch for asset._ref changes]

    WatchChanges --> DetectNew{New asset detected?}
    DetectNew -->|No| RenderDefault
    DetectNew -->|Yes| ApplyTags[applyMediaTags]

    ApplyTags --> ResolveLoop[For each tag name]
    ResolveLoop --> FindTag[Query existing tag by name]
    FindTag --> TagExists{Tag exists?}
    TagExists -->|Yes| UseExisting[Use existing tag]
    TagExists -->|No| CheckCreate{createTagsOnUpload?}
    CheckCreate -->|Yes| CreateTag[Create new tag document]
    CheckCreate -->|No| Skip[Skip tag]

    UseExisting --> CollectRefs[Collect tag references]
    CreateTag --> CollectRefs
    Skip --> CollectRefs

    CollectRefs --> HasRefs{Has valid tags?}
    HasRefs -->|No| Done[Done]
    HasRefs -->|Yes| PatchAsset[Patch asset with tag references]
    PatchAsset --> Done

Loading

Works with both the Media Browser and the native Sanity upload button (including drag-and-drop).

Changes

• New utility: src/utils/applyMediaTags.ts - Finds or creates tags and patches the asset
• New component: src/components/AutoTagInputWrapper/index.tsx - Global input wrapper that detects new asset uploads
• Updated plugin config: Registers the wrapper via form.components.input
• New plugin option: createTagsOnUpload (default: true) - Controls whether non-existent tags should be created automatically
• New exported type: MediaTagsFieldOptions - For TypeScript users to type the field options
• Updated README: Documents the new feature
• New feature: Auto-filter Media Browser by mediaTags when opening from a field

Auto-filtering on browser open

When the Media Browser is opened from an asset field with mediaTags configured:

1. The browser resolves the configured tag names to tag document IDs
2. For each resolved tag, a search facet is added with the references operator
3. Multiple tags use AND logic — only assets matching all tags are shown
4. If tags don't exist yet (not created), they are skipped (no filter applied for that tag)
5. Falls back to showing all assets if no tags could be resolved

New files:

• src/components/Browser/prefilterByMediaTags.ts - Tag resolution and facet seeding logic
• src/components/Browser/useBrowserInit.ts - Initialization hook (assets, tags, real-time sync)

Plugin configuration

media({
  createTagsOnUpload: true // default: true
  // When false, only existing tags will be applied
})

Notes

• The wrapper is transparent - it only activates for image/file fields with mediaTags configured
• For all other inputs, it immediately passes through to the default component with negligible overhead
• Tags are applied asynchronously after upload completes (non-blocking)
• Auto-filtering only applies when opening the browser from an asset source (field context), not when opening the Media tool directly from the studio menu

[vercel]

@einarlove is attempting to deploy a commit to the Sanity Sandbox Team on Vercel.

A member of the Team first needs to authorize it.

[einarlove]

To use this myself, I've created my own forked package while I wait. If you want to test this directly, you can also replace your dependency:

- "sanity-plugin-media": "^4.1.1",
+ "sanity-plugin-media": "npm:@einarlove/sanity-plugin-media@^4.1.1-einarlove.0",

[LucaArgentieri]

To use this myself, I've created my own forked package while I wait. If you want to test this directly, you can also replace your dependency:

- "sanity-plugin-media": "^4.1.1",
+ "sanity-plugin-media": "npm:@einarlove/sanity-plugin-media@^4.1.1-einarlove.0",

This plugin hasn't been updated in a while, has it? Does anyone know why?

[bobbygeo]

Would this be merged soon?

[LucaArgentieri]

Would this be merged soon?

I asked for information on Discord
https://discord.com/channels/1304483263171264613/1367901402621546587/1483720980055462001