Theme Image Block
A theme registers its own images, like a logo or a set of icons, and editors place them as blocks without uploading anything.
WordPress 6.8 or later · PHP 7.4 or later · GPL v2 or later
What it does
A theme has images that belong to it: the logo, a mark, a set of icons, a divider. In the media library they are one click from being replaced, resized, or deleted, and they don’t travel with the theme. Theme Image Block lets a theme register those images in code and gives editors a block that places them. An editor picks an image from a list, picks a style if the theme offers any, and that’s it. The file lives in the theme, deploys with it, and is never uploaded.
This site uses it for the logo in the footer.
How it works
A theme registers each image on init or after_setup_theme, with its path, its size, and alt text. Smaller and larger versions can be registered as variations, and the block builds a srcset from them:
HappyPrime\ThemeImageBlock\register_theme_image(
'logo',
array(
'title' => 'Logo',
'alt' => 'Happy Prime',
'path' => 'images/logo.svg',
'width' => '300',
'height' => '',
)
);Code language: PHP (php)A style gives editors a named size to choose, so a logo can be “Small” in a sidebar and “Hero” at the top of a page without anyone typing a width:
HappyPrime\ThemeImageBlock\register_theme_image_style(
'hero',
array(
'name' => 'Hero',
'width' => 'clamp(10rem, 100vw, 60rem)',
'height' => 'auto',
)
);Code language: PHP (php)In the editor, the Theme Image block lists what the theme registered. Editors choose an image and a style, and can change the alt text when the default isn’t right for the page.
Good for
- A logo or mark that appears on many pages, and must be the same on all of them.
- A set of icons that belongs to the design.
- A network of sites on one theme, where every site should have the same images without each uploading them.
What to know
- Images are registered in code, by whoever maintains the theme. Editors place them; they don’t add new ones.
- The files live in the theme’s folder, so they are versioned and deployed with it.
- The full set of options, including variations and
sizes, is in the readme on GitHub.
