How to add links to images in Portable Text with annotations?

The limitation you're encountering is a fundamental aspect of how Portable Text works. Annotations (like links) only work on inline text spans, not on block-level objects like images. This is by design in the Portable Text specification.

However, there are a few recommended approaches to achieve image linking:

1. Add a link field to your image block (Recommended)

The most straightforward solution is to extend your image block type with a URL field:

{
  type: 'image',
  fields: [
    {
      name: 'alt',
      type: 'string',
      title: 'Alternative text'
    },
    {
      name: 'link',
      type: 'url',
      title: 'Link URL',
      description: 'URL to navigate to when image is clicked'
    }
  ]
}

Then in your frontend renderer, you'd wrap the image with an anchor tag when the link field is present.

2. Create a custom "linked image" block type

You could create a dedicated block type specifically for linked images:

{
  name: 'linkedImage',
  type: 'object',
  title: 'Linked Image',
  fields: [
    {
      name: 'image',
      type: 'image',
      title: 'Image'
    },
    {
      name: 'link',
      type: 'url',
      title: 'Link URL'
    },
    {
      name: 'openInNewTab',
      type: 'boolean',
      title: 'Open in new tab'
    }
  ]
}

Then add this to your Portable Text of array alongside the regular image block.

3. Use an internal reference instead of URL

If you're migrating from WordPress and want to link images to other content in your system:

{
  type: 'image',
  fields: [
    {
      name: 'linkTo',
      type: 'reference',
      title: 'Link to',
      to: [{type: 'post'}, {type: 'page'}]
    }
  ]
}

Why annotations don't work on images

Annotations in Portable Text are specifically designed for inline content within text blocks (spans). Images are block-level objects that exist at the same level as text blocks in the array structure, not within them. This architectural decision keeps the data model clean and predictable.

The approaches above work well because they store the link metadata directly with the image object, which is the appropriate place for block-level content. When rendering, you have full control over how to handle these links in your frontend code.