Img<mds-img>Generated from @maggioli-design-system/magma@2.3.0dist/documentation.json. Encapsulation: shadow.
The first example of the Pattern page, live. Change its props below and the preview follows; Reset brings the example back as it was.
Props
crossoriginenumAllow images from third-party sites that allow cross-origin access to be used with canvas
loadingenumSpecifies whether a browser should load an image immediately or to defer loading of images until some conditions are met.
referrerpolicyenumSpecifies which referrer information to use when fetching an image.
altstringSpecifies an alternate text for an image
heightstringThe height attribute specifies the height of an image, in pixels.
sizesstringOne or more strings separated by commas, indicating a set of source sizes. https://medium.com/@MRWwebDesign/responsive-images-the-sizes-attribute-and-unexpected-image-sizes-882a2eadb6db
srcstringSpecifies the path to the image
srcsetstringSpecifies a list of image files to use in different situations. Defines multiple sizes of the same image, allowing the browser to select the appropriate image source.
srcsetConsumptionstringSpecifies a list of image files to use in different situations. Defines multiple sizes of the same image, allowing the browser to select the appropriate image source based on consumption configuration. <mds-img srcset-consumption="image-black-n-white-1x.jpg low, image-1x.jpg medium, image-2x.jpg high"></mds-img>
widthstringThe width attribute specifies the width of an image, in pixels.
Overview
The <mds-img> web component is the responsive image primitive of the Magma Design System. It wraps the native <img> element, adding accessible defaults, a built-in error/fallback state, and data-consumption-aware source selection driven by the user’s bandwidth preference.
Semantic Behavior
Automatic alt fallback: When alt is omitted or empty, it is derived from the trailing filename segment of src so the image is never left without an accessible name; alt="" therefore does not make the image decorative.Error state: A failed load swaps the picture for a broken-image icon plus the alt text, emitting mdsImgLoadError; changing src clears the error and retries.Load events: mdsImgLoadSuccess and mdsImgLoadError both carry the underlying HTMLImageElement in their detail, letting consumers read natural dimensions or react to failures.Consumption-aware loading: When srcsetConsumption is set, the component reads the persisted consumption preference (the mdsPrefConsumption key that mds-pref-consumption writes, read once on load) and picks the matching source; under the low preference the image is deferred behind a “click to load” placeholder until the user opts in.Localized placeholder: The deferred-load placeholder label is resolved through the shared locale system (el/en/es/it).
Properties & Visual Configurations
Most props are pass-throughs to the native image attributes of the same name (src, srcset, sizes, width, height, loading) and behave as in HTML; pick values as you would for a plain <img>. crossorigin and referrerpolicy exist as props but the current release does not apply them to the inner image. loading defaults to 'lazy', so opt into 'eager' only for above-the-fold imagery.
Other behavioral props
srcsetConsumption is a comma-separated map of sources tagged low / medium / high (e.g. "img-bw.jpg low, img.jpg medium, img@2x.jpg high"). Unlike native srcset, the bucket is chosen by the stored consumption preference rather than viewport, letting low-bandwidth users save data by deferring or downgrading the image.alt supply meaningful text for content images, since it doubles as both the accessible name and the visible label in the error and deferred-load states.