feat(richtext-lexical): separate configuration for lexical block icons

[VeiaG]

This PR adds a new images property to BlockConfig, allowing developers to specify separate images for different UI contexts:

• images.icon — small icon displayed in Lexical editor slash menus and toolbars (20x20px)
• images.thumbnail — larger thumbnail shown in the block selection drawer (3:2 aspect ratio)

Why

Currently, imageURL serves dual purposes:

1. Block selection drawer thumbnails (3:2 aspect ratio, e.g., 480x320px)
2. Lexical editor icons (scaled down to 20x20px)

Citing documentation:

Display Contexts:
Block Selection Drawer: Images appear as thumbnails in a responsive grid when editors add blocks
Lexical Editor: Images are scaled down to 20x20px icons in menus and toolbars

This creates problem , where developer needs to choose either good looking icons (but worse UX on block drawers) or good looking thumnails, but scaled down images as icons.

Solution

Add a dedicated images property with a fallback chain:

Lexical editor icon: images.icon → images.thumbnail → imageURL (deprecated) → default BlockIcon
Block drawer thumbnail: images.thumbnail → imageURL (deprecated) → default placeholder

Now you can set different URL for block icons in lexical blocks:

Example:

  const QuoteBlock: Block = {
    slug: 'quote',
    images: {
      icon: 'https://example.com/icons/quote-20x20.svg',
      thumbnail: { url: 'https://example.com/thumbnails/quote-480x320.jpg', alt: 'Quote block' },
    },
    fields: [...],
  }

Backwards Compatibility

Fully backwards compatible — imageURL and imageAltText still work (marked as @deprecated), with automatic fallback to the new images property behavior.

[AlessioGr]

Let's do the following:

• mark imageURL and imageAltText properties as @deprecated, and add JSDocs
• add one new property:

images?: {
   icon: { url: , alt: },
   thumbnail: { url: , alt: },
}

[VeiaG]

@AlessioGr could you please check packages\richtext-lexical\src\features\blocks\client\getBlockImageComponent.tsx
I got some strange ts error, and only in this file. I don't really know how to fix it, something with ts config.

I moved images to admin.

Moved images to admin properties table in docs, and moved image guidlines section under admin options table

[VeiaG]

About ts error on top, i added NonNullable on Block['admin']. (and removed ts-expect-error) , but i'm not sure if this can break something

export type ClientBlock = {
  admin?: Pick<NonNullable<Block['admin']>, 'custom' | 'disableBlockName' | 'group' | 'images'>
  fields: ClientField[]
  labels?: LabelsClient
} & Pick<Block, 'imageAltText' | 'imageURL' | 'jsx' | 'slug'>

[AlessioGr]

I think this looks good like that, thank you!

[VeiaG]

@AlessioGr pinging, because i removed images config from test blocks configs, for e2e tests to pass.

[VeiaG]

From claude code:

When a block has admin.images.thumbnail with an alt text (e.g. alt: 'Block thumbnail'), the browser includes that alt text in the button's accessible name. The addBlock helper selects blocks in the drawer using:

getByRole('button', { name: exactText(blockToSelect) })

So when searching for 'Content', it expects the button's accessible name to be exactly "Content", but it's now "Block thumbnail Content" — causing the locator to fail.

I moved images config to WithIcon block, and vibe-coded tests for it (sorry).
Locally tests for fields__collections__Blocks don't have same issue.

Pushing here to test.

[github-actions]

🚀 This is included in version v3.79.0