Utility variants

Modify how utility classes behave based on different screen sizes (responsive utilities) or user interactions (state utilities)

Responsive Utilities

You can apply different styles at different responsive breakpoints using responsive utilities.

Responsive breakpoints are the minimum widths at which your layout will change to accommodate different screen sizes. These breakpoints are mobile-first, meaning that styles applied at a given breakpoint will also apply to all larger breakpoints.

Responsive breakpoints

By default, Civic includes nine responsive breakpoints, but not all of them are always available.

Using responsive variants

Use a breakpoint prefix separated with a : to target a utility at a responsive breakpoint and higher. For instance, consider:

<div class="square-8 bg-primary border-2px desktop:border-05"></div>

This will create a square (64px) with a green background (primary background color) with a 2 pixel border below the desktop breakpoint width (1024px) and a 4 pixel border when the screen is at the desktop breakpoint or larger. Resize the width of your screen to see how the border thickness changes on this square.

Responsive variant availability

Not all utilities have responsive variants available. You can see which utilities have responsive variants by checking their individual documentation pages. Here is an example of the responsive settings for the border utility family.

State Utilities

You can apply different styles for different states using state utilities. By default, USWDS includes 4 state variants:

State variants

Hover: This state occurs when the user's mouse pointer is positioned over an interactive element but has not yet clicked or activated it. It is often used to provide visual feedback, such as indicating that the element is interactive.

Active: This state represents an element that is currently being activated by the user, such as when a user is clicking and holding down the mouse button on a link or button. It signifies the brief moment of interaction before the element's action is completed (e.g., navigating to a new page).

Focus: This state indicates that an element is ready to receive input or be activated, typically by a keyboard user using the Tab key to navigate through elements, or programmatically through JavaScript. Elements with focus are often visually highlighted to inform the user which element is currently selected.

Visited: This state applies specifically to links and indicates that the user has previously navigated to the destination of that link. Browsers typically store a history of visited links and can apply a different style (e.g., a different color) to visited links to distinguish them from unvisited ones.

Using state variants

Use a state prefix separated with a : to target a utility for a specific state. For instance, consider:

<button class="usa-button" type="button">Sample button</button>

USWDS has the state variants built into the button component, so it isn't necessary to make them explicit here.

• Without any interaction, the default button color is "primary".
• Mouse over the button and the hover state changes the color to "primary-dark".
• Click the button and the focus state applies a focus outline.
• Click-and-hold the button and the active state changes the color to "primary-darker".
• Use Tab to shift the focus state to the next button.
• The visited state is only applicable to links, so it is not demonstrated here.

If you want to overwrite the default hover state to make the button's background color violet on hover, you would change the code to:

<button class="usa-button hover:bg-violet" type="button">Sample button</button>

State variant availability

Not all utilities have state variants available. You can see which utilities have state variants by checking their individual documentation pages. Here is an example of the state variants for the color utility family.