Documentation
Docs

Image block

The Image block can be used to display different types of media. This documentation gives an overview of the modes that the Image block can operate in and provides copy-pastable examples of images styled in different ways.

Modes

The image block comes with multiple different modes of operation:

ska-blocks Image block modes - File, SVG, Icon, Lottie, Placeholder

Mode – File

Choose an image file from WordPress Media Library, custom URL, upload it or use the Featured image (also works inside the core Query block).

Mode – SVG

Render any SVG image by insert raw SVG content.

Add Tailwind classes to the SVG by using normal block controls, Tailwind classes that are included in raw SVG content do not get detected.

By default the Sanitize option is enabled, which does some basic sanitization so you don’t accidentally XSS yourself when pasting a large unchecked SVG, but it may cause issues with some SVGs so turn it off when you have checked that the contents are not malicious.

Uncheck the Wrap option when you don’t want the <svg> element to be wrapped in an additional element. The Tailwind classes (and other block classes and attributes) you have configured will then be injected directly into the SVG markup that is provided.

Mode – Icon

By switching the Image block to “Icon” mode you can select a SVG icon from available icon packs.

Once you have selected an icon you can also switch back to SVG mode to edit your chosen icon. By default the width and height attributes are removed from bundled SVG icons to make them fluid, how ever if that’s not desirable the values can be recovered in the SVG mode from the data-svg-width and data-svg-height attributes. There are instances where you need the dimensions, and instances where you don’t, depends on the use case and SVG itself. The Icon mode also always wraps the <svg> element, if that is not desirable you can switch back to SVG mode as well, which has an option to toggle that functionality.

ska-icons plugin

By default ska-blocks doesn’t include any icons to keep the plugin size leaner. Download the ska-icons plugin to add Heroicons icons, Feather icons and Font Awesome icons.

ska-icons.zip

Example icon

Icon from: https://heroicons.com

Custom icons

For a few custom icons it’s easiest to just use the Image block in SVG mode and simply paste the icon file contents.

How ever, to add custom icon sets, they should be placed in your child theme directory in the icons folder.
For example: wp-content/themes/ska-theme-child/icons/my-custom-icons/*.svg.
Alternatively you can specify additional icon sources using a filter:

Adding an icon sourcePHP
add_filter('ska_blocks_icon_sources', function($sources) {
	return array_merge([trailingslashit(dirname(__FILE__))], $sources);
});

Mode – Lottie

Allows to render lightweight and scalable animations in the form of a Lottie .json file. Comes with some additional controls to configure how to render the Lottie.

ska-blocks Image block Lottie options

In order to upload .json files to WordPress Media Library you’ll need to enable the ska-blocks -> Options -> Permissions -> JSON uploads option. Alternatively upload the files to your child theme folder and use them with a direct link.

Example Lottie

Lottie from: https://animatedicons.co/icons

Mode – Placeholder

Allows to render a placeholder image to hold a spot for a real image.

When the image block is in “Placeholder” mode, it will display the media picker when clicking on it, allowing to swap out the image with no technical knowledge required:

Media picker in the block editor

ska-theme comes with bundled placeholder images that you can choose from:

Placeholder image selection control

Features

Accessibility

Image block has a “Role” option which can be used to fine-tune its’ semantics:

  • Image (or Link, when the image has a link)
    Applies role="figure" to wrapper element, image should have an alt text provided.
  • Presentation
    Hides the image from assistive technologies, no alt text is needed – use for decorative images.
  • None
    Doesn’t apply any semantics.

When the image has a link you should provide an aria-label or title attribute, unless the image also has a suitable alt-text. When the image is using the “Lightbox” feature then it is also a link, but a “View image in full screen” aria-label is provided automatically.

Wrap & Cover

When the “Wrap” option is enabled then the image is rendered with a wrapper element (e.g. <div> -> <img>). All the Tailwind classes will be applied to the root element, so to target the image you would need to use * or [&>img] variants.

When the image has a link or lightbox then the wrapper element becomes an <a>.

When the image has a wrapper, the “Cover” option can be used to apply object-fit: cover CSS to the image, meaning it will always fill it’s container without any letterboxing. With “Cover” enabled, the image element automatically receives the Tailwind classes: w-full h-full object-cover rounded-[inherit] aspect-[inherit]. Should you need a different mode of object-fit, it can be overridden by adding a Tailwind class such as *:object-contain!.

Resize images on the fly

When using an image from the WP Media Library you can insert custom dimensions and hit Resize to create an image with that size.

"Resize" button in image size selection control
Image resizing controls showing in image size selection control

Specifying a “Custom” size when displaying a Featured image with the Image block will create a suitable size when first visiting the page where the featured image is requested:

"Custom" size selected in image size selection control, with custom dimensions specified

When enabling the “Featured” option (available in “File” mode) the image block will display the current posts Featured image, instead of an image you chose yourself.

Meta key

In “Featured” mode, under block’s Advanced settings a “Meta key” option becomes available – this allows to override the image source from a featured image to a numeric image ID from any post meta key. For example, if you create an Advanced Custom Fields Image field with the “Return format” set to “Image ID” then this field’s value can be connected to the Image block.

Exclusive

By default the single post template displays the featured image below the post title in a predefined size (e.g. 16/9). Sometimes your featured image can be unsuitable to be displayed there or maybe you don’t want to display the featured image at all in a particular post – while still having a featured image attached to the post. For this reason there is an advanced option “Exclusive featured image“, which is enabled by default for ska-theme’s featured images – when enabled, the featured image will not render when the post content also contains an Image block with the Featured option enabled. This allows you to place the featured image anywhere in the blog post content, customize it’s appearance (or hide it – with sr-only class) and not have a duplicate image in your post.

The lightbox feature allows to enable showing the image in full screen using Photoswipe. To make the image “zoomable” enable the “Lightbox” option on the Image block.

Image with a lightbox

Image from: https://picsum.photos

Placeholder image

The same option is also available on the Gallery block, but you may choose to not enable the option and instead use the Lightbox block to combine multiple images and galleries into a single Lightbox instance.

Enabling the “Responsive” option adds srcset and sizes attributes to the image using the WordPress core wp_image_add_srcset_and_sizes function allowing the browser to pick the best image size to load. In order to use this functionality the image needs to be added from the Media Library not from a direct link.

The image block comes with 4 loading modes:

  • Lazy
    Image will use the native loading="lazy" attribute.
  • Eager
    Image will not use the loading="lazy" attribute, so it will be loaded normally.
  • LCP
    Should be selected when the image is part of the Largest Contentful Paint: will use fetchpriority="high" and decoding="sync attributes.
  • Preload
    Can be selected for the highest possible loading priority. Image will be preloaded in the <head> and receives decoding="sync" attribute – use for critical above the fold images.

For critical above the fold images the “Low-res placeholder” option can take a tiny version of the image and use it as a blurry/pixelated background image placeholder for the actual image.

While this method improves user experience by giving them something to look at much faster, it generally does not help with Lighthouse and its’ Largest Contentful Paint (LCP) metric.

The placeholder image can optionally be pre-loaded in the <head> for quick availability.

WordPress core image block can be transformed into a ska/image block:

Transforming core/image block to ska/image block in the block editor

You can paste images from your clipboard directly into the block editor which will upload the image to your WP Media Library and create a core/image block, and then it can be transformed directly into a ska/image block. The transformation can also be done in reverse. For just basic images it’s fine to keep using the core image block, you can transform when advanced flexibility is needed, such as controlling the image loading, accessibility or adding custom HTML attributes.

Inline image

Under block’s Advanced settings, there is a button that can convert the current image into a base64-encoded string and use it as a data-URL. This saves an additional network request on the front end, but should only be used on very small images, as you will effectively be storing the image inside the post content as a string.

Tiny inlined image example

Examples

Rounded image

Circular image

Hover zoom image

Grayscale filter hover transition

Saturated blurry image

Corner cutting with clip-path

Image with a shadow

Accented image

Different image on hover

Skewed image

Flat accent shadow

Stacked accent

Next-gen examples

The new CSS corner-shape property allows for creating unique-looking images. For now there is only support for Chrome-based browsers and there is no Tailwind CSS utility for it so a fully arbitrary class needs to be used (which can be done using the “Variables” feature of ska-blocks).

Squircular image

[corner-shape:squircle] rounded-4xl

Note: when using a wrapper element, you may also need to add *:[corner-shape:inherit] class or apply the corner shape directly to the image element:

Notch

[corner-shape:notch] rounded-4xl

Scoop

[corner-shape:scoop] rounded-[3rem]

Bevel

[corner-shape:bevel] rounded-4xl

[corner-shape:bevel] rounded-full

[corner-shape:bevel] rounded-full aspect-square

Superellipse

[corner-shape:superellipse(-0.25)] rounded-full