Component

ba-image

A wrapper around the native img element that improves image performance and ensures images are displayed consistently

Airframe

Active

Figma

Web Components

Active

Storybook

Github

React

Planned

React Native

Planned

Design

Code

Accessibility

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'`
`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

Slot	Description	Permitted elements
Unnamed slot	Elements will render in the body of the component	None

Parent components

ba-image can be slotted into:

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>`

Usage

Basic usage

In most scenarios you will only need to populate the src, alt and aspect ratio attributes

A basic image component

<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:

Loading different image file sizes at screen widths of 480px, 600px, and 1024px

<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>

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:

No keyboard interactions have been defined for this component.

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

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