Pharos
JSTOR's Design System
 Getting started Help FAQs DocumentationDevelopment GitHub JSTOR LogosTypographyColorImageryIconographyElevationVoice and toneJSTOR termsWeb elementsGrammar and styleEditing checklistAlertButtonBreadcrumbCheckboxCheckbox groupCoach MarkComboboxDropdown menuDropdown menu navFooterHeaderHeadingIconImage cardInput groupLayoutLinkLoading spinnerModalMultiselect dropdownPaginationPillPopoverProgress barRadio buttonRadio groupSelectSheetSidenavSliderSwitchTableTabsToastTooltipText inputTextareaToggle button groupOverviewAlias colorsGlobal colorsFont familyFont sizeFont weightLine heightElevationRadiusSpacingTransitionsType scaleType styles
Skip to main navigation
Button
Buttons communicate actions that users can take.
Example
Primary button

See live code examples in Storybook
Usage

Buttons communicate actions that users can take.

When to use buttons
  • Submit a form
  • Take an action (e.g., download, save, cite, share, publish, upload, etc.)
  • Progress through a series of steps
  • Interact with content (e.g., zooming and paging through items on the viewer)
Determining button priority and hierarchy

Button priorities are determined by the business and user goals of the area or page where they are placed, but also what users want or need to do in a "priority" order.

Primary buttons

Use primary buttons for highest-priority actions that are required to complete the user's task.

Secondary buttons

Use secondary buttons for quieter, but still important actions. They can live on their own, be paired with primary buttons, and also paired with other secondary buttons. Secondary buttons provide less visual noise, and support the visual hierarchy of the primary button.

Multiple buttons

When you need to display multiple actions together in an array, use all secondary buttons (examples, item detail, workspace) OR one primary and the rest secondary buttons. Secondary buttons leave a minimal footprint and aren't as heavy of a distraction within the UI, and primary buttons are reserved for the most important action.

Grouping multiple actions When grouping actions, you can utilize an ellipses icon button paired with a dropdown menu to display a list of actions

If it makes sense to group multiple actions together, you can utilize an ellipses button paired with a dropdown menu. Use this pattern when there are 3 or more actions. Use this pattern sparingly as it does hide actions and adds an extra click for users.

Buttons versus links

Links navigate users to a new page or location. Buttons specifically allow users to perform an action that stays within the context of the page or experience (e.g., the citation button opens a modal or the download button directly downloads an item). There are times where buttons need to act like links and look like buttons to create consistency with the experience. Please read about this variant below and use sparingly in your UI.

Best practices
Dos
  • Buttons should be easy to find among other elements, including other buttons
  • The button's content should be clear and accurately labeled, encouraging a user to take action with an action-oriented verb
  • Prioritize actions within the page and experience based on business and user needs. For most use cases, only one primary button should be used on a page so users are clear about what the most important action is.
  • Use the best variant for your UI needs to communicate meaning and hierarchy.
Don'ts
  • Utilize multiple primary buttons in an array, this causes an imbalance of hierarchy and confusion about what actions should be taken. Reserve primary buttons for the most important action when displaying a series of buttons.
  • Don't use dropdown menus in cases when data is commonly known and easier to type
  • Don't use a button variant for an action it's not intended for.
Content guidelines Action-oriented

Buttons should lead with a strong verb that encourages action. To provide enough context, pair the verb with a noun when applicable.

  • Save
  • Workspace
  • Find my institution
  • Institution finder
Concise

Button text should suggest its action in an expected way and in the fewest words possible. Buttons should be clear, concise and written in sentence case. Avoid unnecessary words and articles such as the, an, or a.

  • Cite
  • Click here to copy the citation
  • Download
  • Download the PDF
Consistent

Make interactive elements consistent in identification and functionality. Don't label a search button "submit" on one page and "enter" on another.

Variants Primary button

Use for primary actions in the page or experience.

Primary button Secondary button

Use for secondary actions in the page or experience. They can also be used for quieter, but still important actions.

Secondary button Subtle button

Use subtle buttons when other types may be too distracting or visually verbose for the area in which it's placed.

Subtle button Overlay button

Use overlay buttons when the button can appear on top of other content like images

Overlay button With icons

Pair text with an icon to better clarify the meaning of the button. Use no more than one icon before text and one icon after text (see Pharos icons ). When deciding to use an icon in a button, it allows for a subtle, but personable, expression of our brand. The icon can also help reinforce the intention of the action. Be consistent with using icons in buttons when placed near other buttons.

With icon button With icon button Icon-only

Use icon-only buttons sparingly and include a label, in most cases that would mean using a tooltip to help visually provide meaning to the action. They should be used only in compact UI situations. Use an icon that conveys a single action.

Back Forward Large button

Only to be used when implementing input groups that use a button so that it matches the height of the input field.

Large secondary button Large primary button
Link button

Use these under careful consideration. Dictation software users may not be able to properly identify these actions, as they can say "show buttons" and these won't highlight since they are semantically links, even though they may look like buttons. These should be used sparingly.

Link button Disabled button

Use the disabled state of a button when a user can't perform an action at the time of their experience. They should be used sparingly and only for actions that they are unable to take. The user shouldn't have to guess why a button is disabled. It should be immediately obvious as to why the button might be disabled (e.g., an item can't be downloaded due to access). Otherwise, show the button in its default state, then provide helpful error text after it's been clicked.

Disabled button Buttons on dark background

When a button is used on a darker background (e.g., black or marble-gray-20), use the is-on-background attribute. The four variants described above can all be used on dark backgrounds and follow the same guidelines.

Primary buttonSecondary button
Accessibility What's built in
  • Ensures component uses the correct semantic button element.
  • Provides built-in focus styles that meet WCAG contrast and visibility requirements.
  • Supports keyboard interactions (e.g., Enter/Space to activate).
  • Includes ability to add ARIA attributes when necessary (e.g., aria-label for icon-only buttons).
  • Variants use predefined color schemes that meet contrast requirements.
Considerations Design
  • Ensure button labels are clear and descriptive (e.g., avoid vague labels like "Click here").
  • Use the disabled state sparingly, as there are known accessibility and usability issues (it removes buttons from the focus order and can add to a users cognitive load). Consider alternative approaches, such as keeping buttons enabled but providing inline messaging about availability.
  • Ensure annotations are used to convey the button's label if using icon-only.
Development
  • Avoid nesting interactive elements (e.g., placing a button inside a link).
  • Use the following attributes as needed:
    • a11y-label: Gives explicit an accessible name with an aria-label attribute
    • a11y-expanded: Conveys associated content’s state with aria-expanded
    • a11y-pressed: Conveys the current pressed state with aria-pressed
    • a11y-haspopup: Indicate an association with another widget via aria-haspopup
    • a11y-disabled: Conveys the disabled state via aria-disabled while keeping it in the focus order
Expected actions Screen reader What is read

VoiceOver reads as: "visual label (or aria-label), button"

Relevant WCAG guidelines
  • 1.3.1 Info and Relationships A
  • 2.5.3 Label in Name AA
  • 4.1.2 Name, Role, Value A