Making Custom Image Sizes Selectable in the Editor

add_image_size() creates files. It does not create a choice. A size registered in a theme or plugin is generated on upload and available to wp_get_attachment_image() in templates, but the Image block's Resolution dropdown and the media modal's size selector only list what image_size_names_choose returns — and by default that is thumbnail, medium, large and full. The filter is the one line between a size that exists and a size an editor can pick.

The working shape

add_action( 'after_setup_theme', 'ti_register_sizes' );

function ti_register_sizes() {
	add_image_size( 'ti-wide', 1600, 900, true );
	add_image_size( 'ti-card', 600, 400, true );
}

add_filter( 'image_size_names_choose', 'ti_size_labels' );

function ti_size_labels( $sizes ) {
	return array_merge( $sizes, array(
		'ti-wide' => __( 'Wide (1600×900)', 'ti' ),
		'ti-card' => __( 'Card (600×400)', 'ti' ),
	) );
}

The array maps size slug to label. The slug must match add_image_size() exactly; the label is free text and benefits from carrying the dimensions, because editors choosing between "Wide" and "Large" otherwise guess. Registering sizes on after_setup_theme (or init in a plugin) is what makes the size exist before any upload is processed.

Why the option is missing for older images

The editor lists a size for an image only when that image has a file at that size. Sizes are generated at upload time, so every image uploaded before the size was registered lacks it, and the dropdown hides the option for those images rather than offering a size that would 404. The fix is regeneration: a thumbnail-regeneration plugin, or wp media regenerate over WP-CLI on larger libraries. Until then the behaviour looks inconsistent — new uploads offer the size, old ones do not — and the inconsistency is the diagnosis.

Regeneration rewrites files for every registered size, which on a large media library takes time and disk. Registering a size you then abandon leaves its files behind forever; remove the registration and the filter together, and consider whether an existing size could have done the job.

Cropping and the label

The fourth argument of add_image_size() decides whether the size is a hard crop to exact dimensions or a proportional resize within a bounding box. A label promising 600×400 is a lie for a soft-cropped size, which produces 600×338 from a 16:9 upload. Say "up to" in the label for soft crops, or use a hard crop and accept that the subject may be cut — the trade-off behind most reports of blurry or badly cropped images is a size registered without thinking about which one applies.

Hiding default sizes

add_filter( 'image_size_names_choose', 'ti_hide_thumbnail_choice' );

function ti_hide_thumbnail_choice( $sizes ) {
	unset( $sizes['thumbnail'] );
	return $sizes;
}

This hides the choice, not the size. The thumbnail file is still generated and still used by the admin's media grid. Stopping a size from being generated is a different filter, intermediate_image_sizes_advanced, or zero dimensions in Settings › Media for the three built-in sizes. Hiding full is possible and rarely wise: it is the only option that guarantees the original is used, which editors need for images already sized for the layout.

The block editor's own behaviour

The Image block offers the sizes from this filter in its Resolution control and writes the chosen size into the block's sizeSlug attribute, and the Gallery, Media & Text and Post Featured Image blocks use the same list for their own Resolution controls. The Cover block uses the full size and scales with CSS. The size the editor pre-selects for a new image is the image_default_size option — large unless changed — and it must be one of the keys this filter returns; a theme that wants a different default overrides that option, or the imageDefaultSize editor setting through block_editor_settings_all, rather than touching the list. Image dimensions in the HTML come from the chosen size, which is also what keeps the layout from shifting as images load.

Verify

• Upload a new image and insert it in a post: the Resolution dropdown lists your labels.
• Choose one and view the page: the src ends in the size's dimensions, such as -600x400.jpg.
• Insert an image uploaded before the size existed: the option is absent until regeneration, and present after.
• Check the generated file's dimensions against the label; a mismatch means the crop argument does not match what the label promises.