Button

A button is used for actions that have an immediate result inside an application such as saving progress or navigating back. It is also used in content sites for Call-to-Action (CTA).

Example Code 
<nys-button label="Button"></nys-button>

Options

Size

Set the size prop of the nys-button to adjust the height of the button. The width of the button is determined by the label. Our current sizes are:

  • sm: Set to 40px in height
  • md: The default size. Set to 48px in height.
  • lg: Set to 56px in height.
Add the `fullWidth` prop to make the button take the width of its container. Default behavior will size the button to fit its label.



Example Code 
<nys-button size="sm" id="button1" name="button1" label="Small"></nys-button>
<nys-button id="button2" name="button2" label="Medium"></nys-button>
<nys-button size="lg" id="button3" name="button3" label="Large"></nys-button>
<nys-button fullWidth size="sm" id="button4" name="button4" label="Small Full"></nys-button>
<nys-button fullWidth id="button5" name="button5" label="Medium Full"></nys-button>
<nys-button fullWidth size="lg" id="button6" name="button6" label="Large Full"></nys-button>

Button Type

Set the type prop of the nys-button to define the button's behavior in a form context. The available types are:

  • button (default): A standard button that does not submit a form.
  • submit: Submits the nearest form when clicked.
  • reset: Resets all inputs in the nearest form to their default values.

Variant

Set the variant prop of the nys-button to adjust the appearance of the button. Our current variants are:

  • filled: The default variant. Use for primary actions.
  • outline: Use for secondary actions.
  • ghost: Use for uncommon actions.
  • text: Use for inline actions.
Example Code 
<nys-button  id="button1" name="button1" label="Filled"></nys-button>
<nys-button  id="button2" name="button2" label="Outline" variant="outline"></nys-button>
<nys-button  id="button3" name="button3" label="Ghost" variant="ghost"></nys-button>
<nys-button  id="button4" name="button4" label="Text" variant="text"></nys-button>

Icons

Set the prefixIcon prop to include an icon in the button. The icon will appear to the left of the label.

Set the suffixIcon prop to include an icon in the button. The icon will appear to the right of the label.

Example Code 
<nys-button id="button1" name="button1" label="Click Me" prefixIcon="chevron_left" suffixIcon="chevron_right"></nys-button>

Disabled

Example Code 
<nys-button disabled id="button1" name="button1" label="Filled"></nys-button>
<nys-button disabled id="button2" name="button2" label="Outline" variant="outline"></nys-button>
<nys-button disabled id="button3" name="button3" label="Ghost" variant="ghost"></nys-button>
<nys-button disabled id="button4" name="button4" label="Text" variant="text"></nys-button>

Link

Set the href prop when using the button to navigate to a different page. This will render the nys-button as an <a> tag.

Example Code 
<nys-button href="https://www.ny.gov/" id="button1" name="button1" label="Visit NY.gov"  ></nys-button>

Inverted

Set the inverted when the button is on a dark background.

Example Code 
<nys-button inverted id="button1" name="button1" label="Filled"></nys-button>
<nys-button inverted id="button2" name="button2" label="Outline" variant="outline"></nys-button>
<nys-button inverted id="button3" name="button3" label="Ghost" variant="ghost"></nys-button>
<nys-button inverted id="button4" name="button4" label="Text" variant="text"></nys-button>

Usage

When to use this component

  • Use for the most important actions you want users to take on your site, such as Download, Sign up or Log out.
  • Use Fill for the primary action on the page; use sparingly, there should be only one primary action on each page.
  • Use Outline for secondary actions; should be placed next to the primary action / Fill button.
  • Use Ghost buttons when there are additional actions beyond primary and secondary.
  • Use Text buttons when an action needs to appear within a text block.

When to consider something else

  • Text Buttons do something, whereas Links go somewhere. Use a Link instead of a text button if clicking the element takes the user somewhere else.

Do

  • Use sentence-case capitalization for button labels.
  • For buttons that open a dropdown use a Chevron Down icon on the right side of the button label.
  • [Dev] Always set the type attribute. Define the purpose and behavior of a button with the type attribute. The type attribute can accept three values: submit, button, and reset. If no type attribute is defined, the button will behave as a submit button.

Don't

  • Don't use buttons for external navigation. Use an HTML link (<a>) or Text button if the result of clicking the element is opening a link of an external page.
  • Don't use icons in buttons without a text label. Very few icons are universally understood.
  • Try not to create new buttons with other styling (color, shape, size). Consistency helps users understand what type of button to look for and what the resulting action will be. If you need additions to NYS Button, or any component, for your application or website please contact the NYSDS team.

Accessibility

The nys-button component includes the following accessibility-focused features:

  • Proper ARIA roles and attributes to ensure screen readers can interpret the toggle correctly.
  • Keyboard navigation support, allowing users to toggle the toggle switch using the keyboard.
  • Visual focus indicators to help users navigate the component.
  • Include a label property to provide accessible text for screen readers.
  • Screen readers handle buttons and links differently. When styling links to look like buttons, remember that screen readers handle links slightly differently than they do buttons. Pressing the Space key triggers a button, but pressing the Enter key triggers a link. Text buttons are read as a button by a screen reader, creating a better experience for users with assistive technology. Ensure you use Text buttons for actions and Links for navigation.

Properties

Property Type
label string
onClick JS function
id string
name string
size string ("sm", "md", "lg")
fullWidth boolean
variant string ("filled", "outline", "ghost", "text")
inverted boolean
prefixIcon `nys-icon` name
suffixIcon `nys-icon` name
disabled boolean
form string
value string
href strong (URL)
type string ("submit", "reset", "button")

CSS Variables


Events

The <nys-button> component emits three custom Javascript events:

  1. click – Fired when the button is clicked.
  2. focus – Fired when the button gains focus.
  3. blur – Fired when the button loses focus.

You can listen to these events using JavaScript:

// Select the button component
  const button = document.querySelector('nys-button');

  // Listen for the 'change' event
  button.addEventListener('click', (event) => {
    console.log('Button Clicked');
  });