Skeleton Loader

A Skeleton Loader is used to display a visual placeholder while content or data is being loaded into the system. It helps communicate system responsiveness and reduces uncertainty, especially in clinical environments where timely data delivery is critical.

Installation instructions

yarn add @department-of-veterans-affairs/clinical-design-system-skeleton npm install @department-of-veterans-affairs/clinical-design-system-skeleton

About this component

Skeleton loaders build trust with users by reinforcing that data is actively loading in the area where they expect content to appear. They enhance the user experience by improving perceived performance and reducing cognitive load during wait times.

Skeleton loaders are particularly advantageous when loading large datasets. By allowing data to load incrementally, users can begin interacting with available content without needing to wait for the entire set to finish loading.

For Designers

The Skeleton Loader component supports two shape variants to reflect the type of content being loaded. Designers should choose the variant that best reflects the final content to minimize layout shifts. Variants

Rectangle: Used to represent text-based content, including body text and headers. This shape helps maintain layout consistency during loading by mimicking the dimensions and placement of text blocks.

Circle: Used to represent non-text or decorative elements, such as images or avatars. This variant is helpful when loading areas of the UI that display profile pictures, icons, or other visual elements. Pattern Example

Guidance

When to use

• To visually indicate that data is being fetched, especially for patient charts, health records, dashboards, or structured content areas.
• When content is broken into sections and loaded progressively (e.g., list views, card grids, or multi-pane layouts).
• When preventing abrupt layout shifts is important to preserve user orientation.

When to consider something else

• If loading is brief (under 300ms), skeleton loaders may be unnecessary and create visual distraction.
• If exact progress feedback is required (e.g., uploading files, syncing), use a progress indicator instead.
• When supporting screen reader-only users, consider using loading text or ARIA live regions instead of visual skeletons.

Benefits

• Builds user trust by visually confirming that content is loading.
• Improves perceived performance and reduces frustration.
• Enables partial content to be revealed progressively rather than waiting for all data to load.
• Reduces layout shift, helping maintain visual consistency during transitions.

Accessibility

The Skeleton Loader includes built-in accessibility support:

• It uses a default role="status" to politely notify assistive technology (AT) users when the loader appears.
• The aria-live property can be set to polite, assertive, or off (default) to control announcement behavior.
• While the loader is active, you should use the ariaBusy boolean prop to indicate loading status. This helps prevent AT from announcing updates before loading is complete.
• The component respects the user’s “reduce motion” system preference—animations are disabled if motion reduction is enabled.

Technical Documentation

Props

component
The component used for the root node. Either a string to use a HTML element or a component.
ElementType<any, keyof IntrinsicElements>


variant
The type of content that will be rendered.
"text""circular""rectangular""rounded"

rows
Number of rows to display. Useful when you want to display a skeleton for multiple rows of items at once.
number
	-
columns
Number of columns to display. Useful when you want to display a skeleton for a grid.
number

	-
height
Height of the skeleton. Useful when you don't want to adapt the skeleton to a text element but for instance a card.

	-
width
Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own.
stringnumber
	-
align
The alignment of each skeleton item. This is useful when you want to align the skeletons in a grid.
"center""left""right"
	-
animation
If true, the skeleton will have a pulse animation.
boolean
	-

role
The role attribute for the skeleton, typically set to "status" for accessibility purposes.
	-

ariaBusy
Indicates whether an element is being modified and that assistive technologies may want to wait until the changes are complete before informing the user about the update.
boolean
	-
ariaLive
The aria-live attribute, indicating the type of updates the screen reader should announce.
"off""assertive""polite"