Skip to main content

Button

Button in Storybook
Note: There are deprecated versions of this component. Switch to a version of the docs older than 10.0.x to view their docs.

Usage​

Overview​

The button is a component that enable users to perform actions and make choices, with a single click. Think of the button as facilitating a conversation between the user and the experience. Most of the time when users encounter text—for example, in an empty state, confirmation, or error—the experience is speaking to the user. Buttons are among the most important components that users interact with. They let users make their purpose known.

When to use​

  • To trigger an action. For example, Submit, Upload, Add, Delete, Save, or Apply.

When not to use​

  • For navigating to new page. Use the link component instead.
  • For uploading files. Use the file uploader component instead.

Formatting​

Anatomy​

image illustrating the anatomy of the button component

Buttons consist of the following elements:

  1. Primary buttons display containers (A) around a text label (B) with an optional icon (C). Primary buttons have a solid background color.
  2. Secondary buttons display containers (A) around a text label (B) with an optional icon (C). Secondary buttons have a visible stroke and no background color.
  3. Tertiary buttons display a text label (B) with an optional icon (C).
  4. Icon buttons display containers (A) around a mandatory icon (C).

Alignment and placement​

When a button group appears as part of a process, such as in a wizard or in a modal, we recommend placing them in the bottom right corner of the page to align with the natural flow of pages. Inside that button group, primary buttons go on the far right.

Do place the primary button on the far right.
Don't place the secondary button on the far right.

For customer configuration, you can set the icon to the left of the button label or the right, but not both at the same time.

For internal Guidewire applications, always position the icon on the right so that the user reads the label first, then sees the icon.

Do set the icon to the right of the button label.
Don't place icons on both the left and right sides of the button label simultaneously.

Button types​

Buttons are rectangular with radiused corners, drop shadows (except for tertiary), simple color treatments, and text labels that use sentence case.

TypePurpose
Primary buttonPrimary buttons are high emphasis. Use them for the most important action. Each page must have only one primary button to trigger the action (not including modal or quick view).
Secondary buttonSecondary buttons are medium emphasis. Use secondary buttons in conjunction with a primary button. As part of a pair, the secondary button's function is to perform the dismissive action of the set. They offer a way for the user to back out and take no action. For example, Cancel versus the primary action Send. Don't use a secondary button in isolation and don't use a secondary button for the main action.
Tertiary buttonTertiary buttons are low emphasis. Use them for less pronounced, and sometimes independent, actions. You can use tertiary buttons in isolation or pair them with a primary button when there are multiple calls to action. When a primary button for the main action is present, you can also use tertiary buttons for sub-tasks on a page.
Icon buttonIcon buttons are intended for widely recognized actions and must appear in conjunction with a tooltip.

Each page must have only one primary trigger action:

Do use only 1 primary button per page.
Don't use more than 1 primary button per page.

Button groups​

Buttons can be grouped to show the relationship between them. We recommend using a 16px gap between buttons (both vertically and horizontally).

Do apply a 16px gap between the buttons in a group.
Don't apply inconsistent spacing between buttons.

Content​

General writing guidelines​

  • Use sentence case for all aspects of designing Guidewire product interfaces. Don't use title case.
  • Use present tense verbs and active voice in most situations.
  • Use common contractions to lend your copy a more natural and informal tone.
  • Use plain language. Avoid unnecessary jargon and complex language.
  • Keep words and sentences short.

Be concise​

  • Keep button labels short and simple: 1 or 2 words, no longer than 4 words.
  • Remove articles (“a”, “an”, and “the”) to support scannability, comprehension, and task completion.

Reference: Nielsen Norman

Keep command text short without sacrificing clarity.
Include no more than 2 to 4 words in a button.

Clearly state the action​

  • For commands that initiate an action or submit information, start button labels with a verb. If the resulting action is not clear from the verb alone, use a noun after the verb to disambiguate the context. For example, Add vehicle instead of Add, or Create schedule instead of Create.
  • Don't use Yes and No for button labels. Name the action that happens when the user clicks.
  • Choose words that logically align with the preceding content: If your headline asks Delete ## object type? then your button text must also say Delete.
  • Take care when using a primary button for a destructive action, especially when it can be triggered by keyboard return. In these instances, be very explicit so there's no ambiguity.

For consistency, see Jutro's content guidelines for a list of recommended action labels.

Lead with verbs or verb phrases.
The words in the button must be accurate, specific, and explicit—not vague.

Use sentence case​

Button text must always be in sentence case. Never use all caps to emphasize a specific button, and don't write in title case.

Refer to the UI text style guide for more information on how to implement sentence case.

Use sentence case for button labels.
Title case hinders readability. Don't use it.

Be mindful of tone​

  • Button labels should tap into users' existing vocabulary. Ask yourself, “Is this a word that a person would actually say in a conversation?”
  • Don't use emojis, exclamation points, or other forms of punctuation in button labels.
Keep button labels to just text.
Emojis and exclamation points aren't appropriate for the utilitarian nature of buttons.

Behaviors​

States​

Buttons have states for enabled, hover, focus, active, disabled, and loading.

StateDescription
Enabled stateEnabledCommunicates to the user that the element is enabled for interaction (default).
Hover stateHoverIndicates that the user has placed a cursor over the element (desktop only). The Hover state can be used with the Enabled and Loading states.
Focus stateFocusIndicates that the user has highlighted the element, typically using an input method such as keyboard or voice. The Focus state can be used with all other states (including Disabled).
Active stateActiveIndicates that the user is clicking or tapping the element. The Active state can be used with the Enabled and Hover states.
Disabled stateDisabledCommunicates to the user that the element is not interactive. Every button is Accessible Disabled by default. That means the disabled button can be focused.
Loading stateLoadingCommunicates to the user that the action is in progress. Use the Loading state when an action is supposed to take more than 1 second. When a button is in the Loading state, the following must happen:
  • Change the text to “Wait…”
  • Disable the possibility to interact with the button. This is a precaution to ensure that users don't make a mistake, such as double-sending something in a form.
  • Maintain the width of the button.
The loading state can be customized. If customers don't want the default loading state (3 pulsating dots), they can wrap their custom one.

Interactions​

Mouse​

The button can be triggered by clicking anywhere inside the button container.

Image of a cursor hovering over a primary button

Keyboard​

When the button has focus, both Space and Enter will activate it.

Screen reader​

The button component uses the implicitly semantic HTML5 <button> tag. Text within the tags acts as the accessible name.

Responsiveness and adaptiveness​

Jutro buttons come in 2 different sizes to accommodate the needs of both enterprise and consumer applications. Enterprise applications require greater data density, and as a result, benefit from smaller buttons and more screen real estate. Like most components, buttons can be distributed, sized, and arranged by our Grid and Flex components as part of Jutro's commitment to responsive design.

Small buttonMedium button
Small buttonMedium button

In mobile experiences, we recommend filling the container width with buttons (the text and icon inside of the button must be centered).

Buttons in mobile experiences fill the container width

Accessibility​

The Jutro button element represents an HTML button that is used to submit information. Text between the opening and closing tags appears as the text of the button.

The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.1 AA requirements. Non-textual content that needs to convey meaning (such as icons and keyboard focus visibility) has a contrast ratio of at least 3:1 with its adjacent colors. All content is visible and functional up to and including 400% without requiring scrolling in two dimensions.

This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance.

Follow the guidance below and refer to the WAI-ARIA Authoring Practices for Buttons when using this component in your applications:

  • The button text must clearly describe the action of the button.
  • If applying custom color themes, check that the contrast ratio of text against its background meets the required threshold.

Accessibly disabled component​

The Button component remains accessibility compliant, even when disabled, as of Jutro version 8.4.0. This functionality is enabled by default for every new app that is created using version 8.4.0 of Jutro or later. Older apps can employ this functionality by adding the accessibleDisabled object to their config.json file and passing props, as shown below.

Accessible disabled Button components have the following characteristics:

  • The disabled HTML attribute is removed.
  • An additional property called aria-disabled is defined.
  • All callback functions, such as onClick and onBlur, are muted and unable to be called.
  • The HTML type attribute value of Button will be changed to button.
  • If the button has the href attribute provided, then its role will be changed to link and its tabIndex will be changed to 0.

Styling for accessible disabled and standard disabled buttons remains the same.