ba-image
A wrapper around the native img element that improves image performance and ensures images are displayed consistently
Airframe
Web Components
React
React Native
Anatomy
Image element
The native img element wrapped by ba-image, displaying the actual image content
Aspect ratio container
The wrapper that maintains the specified aspect ratio and prevents layout shift during image loading
Rounded corners (optional)
A corner treatment applied using the rounded-corners attribute
Design Documentation
Extra space around the edges of an image can distort the UI and may break the look and feel of some pages and components.
Live Demo
<ba-image
alt="Description of image"
src="1920x1080.jpg"
aspect-ratio="16-9"
></ba-image>Properties and attributes
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
alt(required) |
alt |
The 'alt' attribute defines the alternative text for our image.This will be used to help our visually impaired users using screen readers. Also the text can be displayed when an image fails to load |
string |
undefined |
aspectRatio |
aspect-ratio |
Defines a set aspect ratio for our image, sets a proportional relationship between the image's width and height. |
"1-1" | "16-9" | "3-4" | "4-3" | "9-16" | "credit-card" | undefined |
'1-1' |
href |
href |
The URL that the image links to | string | undefined |
undefined |
roundedCorners |
rounded-corners |
Turns on rounded corners for the image | boolean | undefined |
false |
sizes |
sizes |
This defines the image size values | string | undefined |
undefined |
src(required) |
src |
The image URL. This attribute is mandatory for the <img> element. |
string |
undefined |
srcSet |
srcset |
This defines the image srcset values | string | undefined |
undefined |
Permitted ARIA roles
- None
Slots
No slotted content available for this component.
Parent components
ba-image has been deprecated as an option for the media slot in ba-select
Please use a native <img> instead.
ba-image can be slotted into:
<ba‑select><ba‑radio‑card><ba‑page‑segment><ba‑media‑object><ba‑hero><ba‑grid><ba‑flex><ba‑content><ba‑checkbox‑list‑card><ba‑checkbox‑card><ba‑card>
Events
| Event | Description | Type |
|---|---|---|
imgDidLoad |
Emitted when the image has finished loading | CustomEvent<void> |
imgError |
Emitted when the image fails to load | CustomEvent<void> |
imgWillLoad |
Emitted when the image src has been set | CustomEvent<void> |
baClick |
Emitted when the image is clicked and href has been set | CustomEvent<MouseEvent> |
Usage
Basic usage
In most scenarios you will only need to populate the src, alt and aspect ratio attributes
<ba-image alt="Description of the image" src="/url.png" aspect-ratio="4-3"></ba-image>Improve performance by using srcset and sizes attributes
Through the srcset and sizes attributes it is possible to supply a number of different sized images and allow the browser to pick the best image for the device size and current network conditions
Learn more:
- https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images
- https://css-tricks.com/sometimes-sizes-is-quite-important/
<ba-image
alt="Description of image"
srcset="image-at-1024x768.png 1024w, image-at-600x450.png 600w, image-at-480x360.png 480w"
sizes="(max-width: 480px) 480px, (max-width: 600px) 600px, 1024px"
aspect-ratio="4-3"
></ba-image>Using the image as a link in a single page application
<ba-image href="https://ba.com" alt="Visit British Airways" src="/url.png" >Flights to Singapore</ba-image>
<script>
document.querySelector("ba-image").addEventListener("baClick", (event) => {
event.detail.preventDefault();
// Now apply custom SPA routing...
});
</script>Guidelines
People with cognitive disabilities or those with partial sight may have trouble reading text with the authored font family, size and colour. People with low-vision may zoom in a lot, and text within bitmap images gets very pixelated & blurry.
In order to read content comfortably, they may change the visual presentation of the content using their own style sheets.
Text should always be used to present information rather than an image as the presentation of content in an image cannot be changed easily, if required.
If you're provided with an image asset which could be implemented in HTML, recommend this over using the visual asset. Often custom typefaces and visual styling via CSS can achieve desired effect. If this is not possible and text is included in image, try to include the text in HTML elsewhere on the page.
Informative
Provide equivalent alternative text descriptions for non-text content such as images and multimedia to allow people using assistive technologies to understand and enjoy the content on the page.
All images need to have an alt attribute.
Informative images detail
- The content of the alt-text depends on the image and its context. If the image is part of the main content of the page (not a functional image - one that triggers an action), use the alt-text to describe the image in a way that makes sense in the context.
- You don't need to explain that it's an image because screenreaders usually announce that. Keep alt-text to a sentence or 2 and no longer than 250 characters.
- Imagine you were reading the page out to a friend. How would you describe the image?
Decorative
Images that serve a decorative purpose should have a null value (alt="") so that screen readers can ignore the image. If images are not assigned a null value, it can result in a repetitive or confusing experience for screen reader users.
Complex
Infographics require an alternative description in the form of a transcript, this provides a full text-only version of the infographic which can be easily accessed by all users. This can be done by either:
- Providing a link to a new page which contains the transcript;
- Placing the transcript below the image within an accordion, which allows users to hide and show the transcript.
For charts, allow users to access equivalent information in the form of an HTML data table.
Information and tools:
Users should be able to understand the purpose or destination of a link without needing to interpret the visual appearance of an image.
Icons, photographs and illustrations may not have an obvious meaning to everyone, particularly people with cognitive disabilities or people who cannot see the image.
Where the purpose of an image link may be unclear, provide visible text alongside the image that explains what the link does or where it goes.
The link should make sense when encountered independently and should clearly communicate its destination or action.
Keyboard navigation
State: Previous element in DOM has focus and ba-image has href attribute
<a> gets focus
State: <a> has focus
Next tabbable element in the DOM gets focus
Browser navigates to URL in href attribute
Usage and accessibility checklist
Use this checklist to confirm the component has been configured and used correctly.
UX checklist
- ba-image is used with an appropriate aspect-ratio attribute to prevent layout shift
- Use srcset and sizes attributes when multiple image sizes are available to improve performance
- Images do not contain text that would be better implemented as HTML
Accessibility checklist
- ba-image has an alt attribute (either descriptive text or empty string for decorative images)
- Alt text is concise (1-2 sentences, max 250 characters) and describes the image content in context
- Alt text does not start with "image of" or "picture of" as screen readers announce this automatically
- Complex images (infographics, charts) have a transcript or long description available
- Text content is not embedded in images
- Images are not used as the sole means of conveying information or functionality
- Images used as links have clear and distinct alt text that describes the link destination or purpose
- Images used as links are accompanied by visible text that describes the link destination or purpose
- Images used as links have a focus indicator that has not been obscured on all sides of the image
These checks are handled by the component and do not need to be repeated each time it is used.
- Image lazy loading is implemented
- Image loading states are handled appropriately (imgWillLoad, imgDidLoad, imgError events)
- Aspect ratio is maintained across different viewport sizes
- Images respect users' data preferences where applicable
- ba-image is operable using assistive technology
- Has a visible focus indicator on all sides of the image