Skip to main content

Using Preset Image Variants

Preset image variants give you short, repeatable Imgwire delivery URLs for common image sizes. Use them when the same image needs to appear in predictable UI slots such as thumbnails, cards, previews, and documentation hero images.

How presets work​

Imgwire presets are appended to the image path before query parameters:

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}@medium

The supported preset suffixes are:

PresetURL suffixCommon use
thumbnail@thumbnailProfile pictures, small previews, and image lists
small@smallCompact cards and secondary UI images
medium@mediumDocumentation images, feature cards, and embeds
large@largeHero images and wide content areas

If you are using an SDK, pass the preset by name instead of hand-building the suffix:

const url = image.url({
  preset: 'medium',
  format: 'auto',
  quality: 'auto',
});

When to use presets​

Use presets when the layout slot is common across your application and does not need one-off dimensions. This keeps image URLs easier to read, makes CDN variants more reusable, and gives your team a shared vocabulary for image sizes.

Good preset candidates include:

  • Profile pictures, avatar grids, and thumbnail grids.
  • CMS or admin previews.
  • Documentation screenshots.
  • Blog card images.
  • Marketing images with a standard medium or large placement.

Use explicit transformations when the placement needs exact dimensions, crop behavior, DPR variants, or a format-specific setting:

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=1200&height=630&resizing_type=cover&format=auto&quality=auto

Combine presets with delivery options​

Presets can still be combined with transformation query parameters. A common production pattern is to use a preset for size and request automatic delivery behavior:

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}@medium?format=auto&quality=auto

format=auto lets Imgwire choose a browser-friendly output format, and quality=auto lets Imgwire choose a practical compression setting for the delivered variant. These options affect the delivered image response, not the original upload.

Presets can also be combined with Gravity. This is useful for profile pictures and user-uploaded thumbnails where the important region may not be centered:

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}@thumbnail?gravity=attention&format=auto&quality=auto
const url = image.url({
  preset: 'thumbnail',
  gravity: 'attention',
  format: 'auto',
  quality: 'auto',
});

Responsive image strategy​

Presets are useful for named sizes, but responsive layouts usually need more than one candidate. Use width-based variants or the React <ResponsiveImage /> component when the browser should choose the best image for the viewport.

<ResponsiveImage
  id="img_123"
  alt="Product gallery image"
  format="auto"
  quality="auto"
  breakpoints={{
    sm: { minWidth: 0, width: 320 },
    md: { minWidth: 640, width: 640 },
    lg: { minWidth: 1024, width: 1024 },
  }}
/>

For the full pattern, see responsive image variants with srcset.

Best practices​

  • Use presets for repeated UI slots and explicit transformations for layout-specific variants.
  • Store the Imgwire image ID when your app may need to generate more variants later.
  • Pair public preset URLs with format=auto and quality=auto unless the design requires a specific output format or quality.
  • Pair @thumbnail with gravity=attention for profile pictures and user-generated thumbnails where the subject may be off-center.
  • Keep preset usage consistent across the app so the same variant can be reused from cache.
  • Use meaningful alt text at render time; a preset only controls delivery, not accessibility.

Common mistakes​

  • Treating presets as the only responsive image strategy. For fluid layouts, generate a real srcset.
  • Using a large preset for small UI elements because it looks sharp during development.
  • Hard-coding complex URLs everywhere instead of using SDK helpers, the CLI, or MCP tools to generate them.

Last updated at: May 10, 2026