Image

Usage

• Use Image to display any raster or vector asset in the UI — product logos and branding marks, illustrative graphics in empty states and onboarding flows, user-uploaded content such as account logos and asset library previews, third-party integration icons loaded from external URLs, and decorative images paired with marketing or instructional copy.
• Use Image for a custom icon when no Pluma icon fits. Set a preset size, objectFit="contain", and withBoundingBox so it occupies the same dimensions and inner spacing as an Icon.
• Use Icon instead when the graphic is part of the Pluma Icon library and should inherit text color.
• Keep every Image and Icon in the same group at one size. Never mix sizes within a group.

Appearance

• Bounding box (withBoundingBox) — adds padding proportional to the image's size so the image aligns with adjacent same-size Icons. Without it the image fills the full size and reads visually larger than a same-sized Icon.
• Object fit (objectFit) — controls how the image resizes when the container's aspect ratio differs from the image's:
  • "contain" — scales to fit entirely, preserving aspect ratio. Use for logos and icons that must never be cropped.
  • "cover" — scales and crops to fill the container. Use for hero images and thumbnails.
  • "fill" — stretches to the container's exact dimensions, ignoring aspect ratio.
  • "scale-down" — like contain, but never scales the image larger than its intrinsic size.
• Sizes (size) — preset sizes follow the Icon scale so Images and Icons are interchangeable: "icon-v2-sm", "icon-v2-md", "icon-v2-lg", "icon-v2-xl". Use them when an Image sits alongside Icons at the same visual weight.
• With no preset size, the image renders at its natural dimensions or at explicit width and height values.

Behaviors

• Coin integration — inside a Coin, Image inherits the Coin's size, object-fit, and bounding box. Pass no sizing props.
• Color scheme variants — pass src as an array of ImageSource entries, each tagged with a colorScheme of "light" or "dark", so the asset swaps when the theme toggles. Use for graphics and logos that have light and dark variations.
• Inline display (isInline) — renders the image inline with surrounding text and shifts it vertically to sit alongside the letters, matching inline Icon behavior.

Content

• Give every Image an alt attribute.
• Decorative images — set alt="".
• Functional images — describe the action or destination, e.g. "Customer.io homepage".
• Informative images — describe what the image communicates in context, e.g. "Bar chart showing delivery rate over time".

Implementation Notes

• Image extends Box and accepts every Box layout and sprinkle prop (w, h, p, …) alongside its own props.
• Image is polymorphic via as and defaults to img.
• The component sets alt="" by default and consumer-supplied alt overrides it. In Ember, alt is a plain HTML attribute, not an @arg.
• src accepts a string or a readonly array of ImageSource. A string renders a single <img>; an array renders a <picture> with one <source> per entry plus a fallback <img>. An array whose entries are all filtered out renders a bare <img> with no <picture> wrapper.
• ImageSource fields: src, colorScheme, media, srcSet, sizes, height, width. colorScheme is translated into a prefers-color-scheme media query; when the entry also sets media, the two are combined with and.
• Color-scheme swapping depends on the PlumaProvider color-scheme preference. Under "auto" every entry is rendered and the browser picks; under an explicit "light" or "dark" only entries matching that scheme — or entries with no colorScheme — are rendered.
• The fallback <img> src is the first entry with neither colorScheme nor media, otherwise the first entry in the array.
• objectFit also accepts "none", and legacy v1 sizes "icon-xxs", "icon-xs", "icon-sm", "icon-md", "icon-lg", and "icon-xl" are still available. Prefer the v2 sizes.
• inlineAlignment accepts "uppercase" (applied by default when isInline is set) or "lowercase". It only applies when isInline is set.
• Coin defaults apply only when the Coin's imageFit is not "cover". With imageFit="cover", the size and bounding-box defaults are dropped and the image stretches to fill the coin shape. Explicitly set props always win over the Coin defaults.
• iconSizeToImageSize(iconSize, sizeVersion?) converts an Icon size to the matching Image size. It auto-detects v1 for "xxs" and "xs" and v2 otherwise.
• Ember: invoke as <PlumaImage @src={{...}} @size="icon-v2-lg" @objectFit="contain" @withBoundingBox={{true}} alt="…" /> — component props use @argName syntax.