Skip to content


The Img component enforces opinionated attributes that improve accessibility and page load experience. This page also contains information on best practices when working with images.

Img is a wrapper around the native img element that enforces the inclusion of four important attributes:

Required properties for the Img component
altAlternative text is read aloud by screen readers to describe the contents of an image. It also replaces an image if it doesn’t load for any reason. Read more about alternative text »
heightThe intrinsic height of the image. This information helps the browser efficiently paint the UI.
widthThe intrinsic width of the image. This information helps the browser efficiently paint the UI.
loadingWe leverage native lazy loading by default.

Note: Borders are shown on Box in these examples to illustrate the relationship between Box and Img. These examples are resizable to help understand how images respond to their containers.

This basic implementation loads a single image source and demonstrates how we default to responsive imagery with the fit property.

This image has an intrinsic width of 304, but fit="container" uses CSS to set the image width to 100% of the width of its container; the browser will determine the appropriate height. In this example, the width of Box is set to 33% of its container.

In this example, we use fit="content", which displays the image at the values passed to height and width. The image will not resize and will overflow its container if the container shrinks; resize this example to see the effect. Use with caution in mobile design.

This example illustrates the use of srcset, which provides the browser with a variety of sources to display at its discretion in order to optimize loading.

The image widths are specified in the syntax, which enables the browser to choose the best image based on viewport size, bandwidth, screen density, etc.Note the w in the syntax; this syntax indicates that you are specifying a width rather than a pixel density, so don’t leave it out.

The srcset attribute is supported by all of Gusto’s supported browsers, but you must still include a source in the src attribute.

Alternative text is intended to describe the visual contents of an image for visually impaired users. The text should include a clear explanation of perspective and non-visual senses (e.g. touch, smell).

Alt text is commonly confused with caption text that creates a marketing/promotional relationship between the image and some content, but there are better options for this kind of text (read more about titles and captions below).

How might we describe this image?

Penny the pig, Gusto's cartoon mascot
This is Penny the pig, Gusto's mascot. Sighted users can probably visualize a cartoon pig, but visually impaired users may have never seen a pig and may not understand the reference. Instead of describing this image as “A pig named penny”, we might describe it as “Penny, Gusto's cartoon pig mascot”. Visually impaired people might not know what a pig looks like, but might have learned what they feel like through texture learning, and understand the payroll/piggy bank mascot reference.

Screen readers will automatically announce images as such, so you do not need to add “An image of…” to your descriptions. If the image truly does not add any value to the content of the page, mark it as being decorative to instruct screen readers to skip over it.

Alt text can and should also be used to test images with React Testing Library.

expect(screen.getByAltText('Black lab puppy on a wood floor')).toBeInTheDocument();

Read more on Mozilla about authoring meaningful alternative text

A cartoon pig named Penny
A colorful fall landscape
A check made out for $100
Good alternative text describes the contents of the image.
This is Penny
It looks so cozy!
Your paycheck is delightful
Don’t present information that relies upon comprehension of the image.
Penny the pig, Gusto's cartoon mascot
alt="Penny the pig, Gusto's cartoon mascot"
This example describes the image (Gusto's mascot, a pig named Penny).
This is Penny
alt="This is Penny"
A visually impaired user would not understand who or what Penny is.

Native lazy loading is now available on all of Gusto’s supported browsersexcept Safari, where it has been introduced in an early preview build. We leverage this feature by default to improve page load performance.

Use loading="eager" for critical images that should be prioritized, i.e. images above-the-fold.

<Img src={imagePath} alt="A fluffy kitten" loading="eager" height={200} width={300} />

Text supplied to the title attribute will appear as a tooltip on mouse hover.

This text will not be made available to users of touch screens (mobile devices) and keyboards (assistive technologies), so it should not be used for critical information. This text should be considered supplemental information; the UI should be usable and comprehensible without it.

Below is a contrived example to illustrate title text that isn’t particularly helpful, but neither is it detrimental. Realistically, it would be better to alter the alt text to read “Gusto's mascot, a cartoon pig named Penny”.

alt="This is Penny"
title="Penny, Gusto's cartoon pig mascot"

The figure and figcaption elements are used to associate an image with visible caption text.

This is not a common use case within Gusto, so we do not have a component or any particular styling for the native elements. Contact Design Systems if you have a proposal that may be useful to other teams.

Read more about the figure element »

alt="A cartoon pig named Penny"
<figcaption>This is Gusto's mascot, a cartoon pig named Penny</figcaption>

Some images are purely decorative and don’t add any information to the content of the page. We can mark these images with role="presentation", which spares screen readers from presenting them to users.

<Img src={imagePath} alt="A fluffy kitten" role="presentation" height={200} width={300} />

Most images in Gusto will come from our own illustration or icon libraries and are served as SVGs, which are crisp and infinitely scalable. We don’t have hard and fast rules, but we generally aim for these guidelines:

  • Small illos: < 15kb
  • Medium illos: < 50kb
  • Large illos: < 100kb
  • SVGs are preferred when file size is reasonable
  • If your file size is > 25kb, start thinking of using a PNG
  • When using PNG, you’ll also need to consider supplying sources for high density screens (see using srcset)
  • All images, regardless of format, should be optimized; try Squoosh or ImageOptim

All native image attributes will be passed to the img element.

React props
alt  RequiredstringA description of the image that is read to screen readers.
fit  contentcontainercontainerEstablishes whether the image should resize to the height of its container ("container") or maintain its intrinsic dimensions ("content").
height  RequiredstringnumberThe height of the native image.
loading  eagerlazylazyEnables native lazy loading on browsers that support it (i.e. not Safari).
width  RequiredstringnumberThe width of the native image.

Images are displayed inline by default and can be centered in CSS using text-align: center or textAlign="center" if using Box, Grid, or Flex.

If the image occupies its entire container (as with fit="container"), you can use other methods for centering block-level elements, such as margin: 0 auto or alignItems: center in the context of Grid or Flex.

The following testing snippet(s) offer suggestions for testing the component using React Testing Library with occasional help from Jest.

alt="Black lab puppy on a wood floor"
expect(screen.getByAltText('Black lab puppy on a wood floor')).toBeInTheDocument();