Media
Image
Images are a type of visual media. They can appear at fixed sizes, percentages, and aspect ratios.
Interactive demo
This demo allows you to preview the image component, its variations, and configuration options.
Anatomy
The image component contains two required elements and two optional elements.
| Item | Name | Description | Component | Optional |
|---|
Options
The image has options for different use cases:
Image dimensions
The width and height dimensions of an image can be set to fixed sizes or percentages.
Placeholder icon
The image has a placeholder icon that can be used to display a custom icon e.g. brand logo.
Caption
A caption component can be added to an image with an optional credit to the image source.
Image dimensions
The width and height dimensions of an image can be set to fixed sizes or percentages.
Placeholder icon
The image has a placeholder icon that can be used to display a custom icon e.g. brand logo.
Caption
A caption component can be added to an image with an optional credit to the image source.
States
The image has the following states:
Base
The default style of the image when loaded.
Loading
Communicates that an image will be shown available when loading is complete, indicated with a placeholder icon. This state can be skipped when the renderOnServer prop is set to 'true'.
Behaviours
Here’s how the image behaves:
Loading
When in a loading state, the loading container of the image can determine the height or width of the image if only one dimension is provided. Image loading can be set to 'lazy' which will wait until the browser estimates it will be needed. Or 'eager' which will load the image as soon as possible.
Loading
When in a loading state, the loading container of the image can determine the height or width of the image if only one dimension is provided. Image loading can be set to 'lazy' which will wait until the browser estimates it will be needed. Or 'eager' which will load the image as soon as possible.
Usage
Here's how and when to use the image:
Don’t use text in images
Avoid including text in images, as screen readers will not be able to read the words.
Accessibility considerations
Image alt text
Always provide an alternative text description that describes the information or function the image represents via the alt prop. This will allow screen readers and any other assistive technology to understand the image.
This alt-decision tree is helpful for determining whether and how to provide alternative text.
Alt-text is not usually visible but is read out by screen readers or displayed if an image does not load or if images have been switched off.
SEO
Ensure placeholder icons have alt text applied.
API
The image has a range of props to define the experience in different use cases.
| Name | Type | Default | Description | Required |
|---|