Image and gallery

Image holds a single image: a logo, a portrait, a floor plan. Gallery holds several images in the order the editor drags them into: the photos of a book launch, the slides of a carousel.

Image or featured image?

If a post type needs one main image, use WordPress's own Featured image. Themes, social previews and SEO plugins already know where to find it. Add an Image field only for additional images, like a logo alongside the main photo.

Settings

Both share the upload settings. Gallery also has:

• Minimum files and Maximum files: how many images the gallery can hold.
• Max total size (KB): a limit on all images combined.

Image sizes

When an image is uploaded through the field, WordPress normally generates a set of resized copies (thumbnail, medium, large and so on). Generated image derivatives controls that per field: all registered sizes, none, or only the sizes you pick. Generating fewer sizes saves disk space on sites with many uploads, but a theme that asks for a size that wasn't generated gets the full image instead.

Displaying them

In the block editor, bind an Image field to an Image or Cover block with a dynamic tag, and loop over a Gallery with a data loop. Each image offers its URL, alt text, title, caption and attachment ID.

Technical details for LLMs

• Type keys: image (single; max_files fixed at 1), gallery (multi).
• Settings: allowed_mime_types, max_file_size_kb, min_files, max_files, max_total_size_kb (gallery), private_upload, upload_dir, image_derivatives (all | none | selected; default all), image_derivative_sizes.
• Stored: image → attachment id as a string; gallery → JSON array of attachment ids, in order.
• Abilities: read a media object (image) or an array of them (gallery); write an attachment id / array of ids, validated against the field's policy.
• PHP: ->image() / ->media() → Media_Value (->url( 'large' ), alt, dimensions); ->gallery() → Media_Value[].