About Project Overview Contributing Getting Started Installation Usage Themes Customizing Frameworks React Vue Angular GitHub Light Dark System

Button

<terra-button> | TerraButton
Since 1.0 stable

Buttons represent actions that are available to the user.

Button
<terra-button>Button</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => <TerraButton>Button</TerraButton>;

Examples

Variants

Use the variant attribute to set the button’s variant.

Default Primary Success Warning Danger 
<terra-button variant="default">Default</terra-button>
<terra-button variant="primary">Primary</terra-button>
<terra-button variant="success">Success</terra-button>
<terra-button variant="warning">Warning</terra-button>
<terra-button variant="danger">Danger</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton variant="default">Default</TerraButton>
    <TerraButton variant="primary">Primary</TerraButton>
    <TerraButton variant="success">Success</TerraButton>
    <TerraButton variant="warning">Warning</TerraButton>
    <TerraButton variant="danger">Danger</TerraButton>
  </>
);

Sizes

Use the size attribute to change a button’s size.

Small Medium Large 
<terra-button size="small">Small</terra-button>
<terra-button size="medium">Medium</terra-button>
<terra-button size="large">Large</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton size="small">Small</TerraButton>
    <TerraButton size="medium">Medium</TerraButton>
    <TerraButton size="large">Large</TerraButton>
  </>
);

Outline Buttons

Use the outline attribute to draw outlined buttons with transparent backgrounds.

Default Primary Success Warning Danger 
<terra-button variant="default" outline>Default</terra-button>
<terra-button variant="primary" outline>Primary</terra-button>
<terra-button variant="success" outline>Success</terra-button>
<terra-button variant="warning" outline>Warning</terra-button>
<terra-button variant="danger" outline>Danger</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton variant="default" outline>
      Default
    </TerraButton>
    <TerraButton variant="primary" outline>
      Primary
    </TerraButton>
    <TerraButton variant="success" outline>
      Success
    </TerraButton>
    <TerraButton variant="warning" outline>
      Warning
    </TerraButton>
    <TerraButton variant="danger" outline>
      Danger
    </TerraButton>
  </>
);

Circle Buttons 

<terra-button circle>
  <slot name="label">
    <terra-icon name="solid-play" library="heroicons" font-size="1.5em"></terra-icon>
  </slot>
</terra-button>
<terra-button variant="danger" circle>
  <slot name="label">
    <terra-icon name="outline-arrow-down-tray" library="heroicons" font-size="1.5em"></terra-icon>
  </slot>
</terra-button>
<terra-button outline circle>
  <slot name="label">
    <terra-icon name="outline-arrow-down-tray" library="heroicons" font-size="1.5em"></terra-icon>
  </slot>
</terra-button>
<terra-button size="small" circle>
  <slot name="label">
    <terra-icon name="outline-arrow-down-tray" library="heroicons" font-size="1.3em"></terra-icon>
  </slot>
</terra-button>
<terra-button size="large" circle>
  <slot name="label">
    <terra-icon name="outline-arrow-down-tray" library="heroicons" font-size="2em"></terra-icon>
  </slot>
</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const = App = () => (
  <>
    <TerraButton circle>
      <slot name="label">
        <TerraIcon name="solid-play" library="heroicons" font-size="1.5em"></TerraIcon>
      </slot>
    </TerraButton>
    <TerraButton variant="danger" circle>
      <slot name="label">
        <TerraIcon name="outline-arrow-down-tray" library="heroicons" font-size="1.5em"></TerraIcon>
      </slot>
    </TerraButton>
    <TerraButton outline circle>
      <slot name="label">
        <TerraIcon name="outline-arrow-down-tray" library="heroicons" font-size="1.5em"></TerraIcon>
      </slot>
    </TerraButton>
    <TerraButton size="small" circle>
      <slot name="label">
        <TerraIcon name="outline-arrow-down-tray" library="heroicons" font-size="1.3em"></TerraIcon>
      </slot>
    </TerraButton>
    <TerraButton size="large" circle>
      <slot name="label">
        <TerraIcon name="outline-arrow-down-tray" library="heroicons" font-size="2em"></TerraIcon>
      </slot>
    </TerraButton>
  </>
)

Text Buttons

Use the text variant to create text buttons that share the same size as regular buttons but don’t have backgrounds or borders.

Text Text Text 
<terra-button variant="text" size="small">Text</terra-button>
<terra-button variant="text" size="medium">Text</terra-button>
<terra-button variant="text" size="large">Text</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton variant="text" size="small">
      Text
    </TerraButton>
    <TerraButton variant="text" size="medium">
      Text
    </TerraButton>
    <TerraButton variant="text" size="large">
      Text
    </TerraButton>
  </>
);

Page Link Buttons

Use the pagelink variant to create text buttons that use bold text and a red circled arrow icon to indicate navigation to a new page. Links to external content (outside of the hosting domain) will render an arrow pointing to the upper right to indicate that the user will be leaving the hosting site.

Explore Explore Explore 
<terra-button variant="pagelink" href="https://localhost/" target="_blank" size="small">Explore</terra-button>
<terra-button variant="pagelink" href="https://localhost/" size="medium">Explore</terra-button>
<terra-button variant="pagelink" href="https://example.com/" target="_blank" size="large">Explore</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton variant="pagelink" href="https://localhost/" target="_blank" size="small">
      Explore
    </TerraButton>
    <TerraButton variant="pagelink" href="https://localhost/" size="medium">
      Explore
    </TerraButton>
    <TerraButton variant="pagelink" href="https://example.com/" target="_blank" size="large">
      Explore
    </TerraButton>
  </>
);

It’s often helpful to have a button that works like a link. This is possible by setting the href attribute, which will make the component render an <a> under the hood. This gives you all the default link behavior the browser provides (e.g. CMD/CTRL/SHIFT + CLICK) and exposes the target and download attributes.

Link New Window Download Disabled 
<terra-button href="https://example.com/">Link</terra-button>
<terra-button href="https://example.com/" target="_blank">New Window</terra-button>
<terra-button href="/assets/images/wordmark.svg" download="shoelace.svg">Download</terra-button>
<terra-button href="https://example.com/" disabled>Disabled</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton href="https://example.com/">Link</TerraButton>
    <TerraButton href="https://example.com/" target="_blank">
      New Window
    </TerraButton>
    <TerraButton href="/assets/images/wordmark.svg" download="shoelace.svg">
      Download
    </TerraButton>
    <TerraButton href="https://example.com/" disabled>
      Disabled
    </TerraButton>
  </>
);

Setting a Custom Width

As expected, buttons can be given a custom width by passing inline styles to the component (or using a class). This is useful for making buttons span the full width of their container on smaller screens.

Small Medium Large 
<terra-button variant="default" size="small" style="width: 100%; margin-bottom: 1rem;">Small</terra-button>
<terra-button variant="default" size="medium" style="width: 100%; margin-bottom: 1rem;">Medium</terra-button>
<terra-button variant="default" size="large" style="width: 100%;">Large</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton variant="default" size="small" style={{ width: '100%', marginBottom: '1rem' }}>
      Small
    </TerraButton>
    <TerraButton variant="default" size="medium" style={{ width: '100%', marginBottom: '1rem' }}>
      Medium
    </TerraButton>
    <TerraButton variant="default" size="large" style={{ width: '100%' }}>
      Large
    </TerraButton>
  </>
);

Prefix and Suffix Icons

TODO

Caret

Use the caret attribute to add a dropdown indicator when a button will trigger a dropdown, menu, or popover.

Small Medium Large 
<terra-button size="small" caret>Small</terra-button>
<terra-button size="medium" caret>Medium</terra-button>
<terra-button size="large" caret>Large</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton size="small" caret>
      Small
    </TerraButton>
    <TerraButton size="medium" caret>
      Medium
    </TerraButton>
    <TerraButton size="large" caret>
      Large
    </TerraButton>
  </>
);

Shape

Use the button shape attribute to override its radius. Useful for controlling the button’s edge shape when it is next to an input form controls such as a drop-down list but not in a terra-button-group. The button will appear more integrated into input form controls such as drop-down lists, search fields, etc.

Square-right Square Square-left 
<terra-button shape="square-right">Square-right</terra-button>
<terra-button shape="square">Square</terra-button>
<terra-button shape="square-left">Square-left</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton shape="square-right">
      Small
    </TerraButton>
    <TerraButton shape="square">
      Medium
    </TerraButton>
    <TerraButton shape="square-left">
      Large
    </TerraButton>
  </>
);

Loading

Use the loading attribute to make a button busy. The width will remain the same as before, preventing adjacent elements from moving around.

Default Success Warning Danger 
<terra-button variant="default" loading>Default</terra-button>
<terra-button variant="success" loading>Success</terra-button>
<terra-button variant="warning" loading>Warning</terra-button>
<terra-button variant="danger" loading>Danger</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton variant="default" loading>
      Default
    </TerraButton>
    <TerraButton variant="success" loading>
      Success
    </TerraButton>
    <TerraButton variant="warning" loading>
      Warning
    </TerraButton>
    <TerraButton variant="danger" loading>
      Danger
    </TerraButton>
  </>
);

Disabled

Use the disabled attribute to disable a button.

Default Success Warning Danger 
<terra-button variant="default" disabled>Default</terra-button>
<terra-button variant="success" disabled>Success</terra-button>
<terra-button variant="warning" disabled>Warning</terra-button>
<terra-button variant="danger" disabled>Danger</terra-button>

import TerraButton from '@nasa-terra/components/dist/react/button';

const App = () => (
  <>
    <TerraButton variant="default" disabled>
      Default
    </TerraButton>

    <TerraButton variant="success" disabled>
      Success
    </TerraButton>

    <TerraButton variant="warning" disabled>
      Warning
    </TerraButton>

    <TerraButton variant="danger" disabled>
      Danger
    </TerraButton>
  </>
);

Styling Buttons

This example demonstrates how to style buttons using a custom class. This is the recommended approach if you need to add additional variations. To customize an existing variation, modify the selector to target the button’s variant attribute instead of a class (e.g. terra-button[variant="primary"]).

Pink Button 
<terra-button class="pink">Pink Button</terra-button>

<style>
  terra-button.pink::part(base) {
    /* Set design tokens for height and border width */
    --terra-input-height-medium: 48px;
    --terra-input-border-width: 4px;

    border-radius: 0;
    background-color: #ff1493;
    border-top-color: #ff7ac1;
    border-left-color: #ff7ac1;
    border-bottom-color: #ad005c;
    border-right-color: #ad005c;
    color: white;
    font-size: 1.125rem;
    box-shadow: 0 2px 10px #0002;
    transition: var(--terra-transition-medium) transform ease, var(--terra-transition-medium) border ease;
  }

  terra-button.pink::part(base):hover {
    transform: scale(1.05) rotate(-1deg);
  }

  terra-button.pink::part(base):active {
    border-top-color: #ad005c;
    border-right-color: #ff7ac1;
    border-bottom-color: #ff7ac1;
    border-left-color: #ad005c;
    transform: scale(1.05) rotate(-1deg) translateY(2px);
  }

  terra-button.pink::part(base):focus-visible {
    outline: dashed 2px deeppink;
    outline-offset: 4px;
  }
</style>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/button/button.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/button/button.js';

To import this component using a bundler:

import '@nasa-terra/components/dist/components/button/button.js';

To import this component as a React component:

import TerraButton from '@nasa-terra/components/dist/react/button';

Slots

Name Description
(default) The button’s label.
prefix A presentational prefix icon or similar element.
suffix A presentational suffix icon or similar element.

Learn more about using slots.

Properties

Name Description Reflects Type Default
variant The button’s theme variant. 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'text' | 'pagelink' 'primary'
size The button’s size. 'small' | 'medium' | 'large' 'medium'
caret Draws the button with a caret. Used to indicate that the button triggers a dropdown menu or similar behavior. boolean false
shape The button’s shape. Used to control the radius edge shape when button is not in a terra-button-group. 'square' | 'square-left' | 'square-right' -
disabled Disables the button. boolean false
loading Draws the button in a loading state. boolean false
outline Draws an outlined button. boolean false
circle Draws a circular icon button. When this attribute is present, the button expects a single <terra-icon> in the default slot. boolean false
type The type of button. Note that the default value is button instead of submit, which is opposite of how native <button> elements behave. When the type is submit, the button will submit the surrounding form. 'button' | 'submit' | 'reset' 'button'
name The name of the button, submitted as a name/value pair with form data, but only when this button is the submitter. This attribute is ignored when href is present. string ''
value The value of the button, submitted as a pair with the button’s name as part of the form data, but only when this button is the submitter. This attribute is ignored when href is present. string ''
href When set, the underlying button will be rendered as an <a> with this href instead of a <button>. string ''
target Tells the browser where to open the link. Only used when href is present. '_blank' | '_parent' | '_self' | '_top' -
rel When using href, this attribute will map to the underlying link’s rel attribute. Unlike regular links, the default is noreferrer noopener to prevent security exploits. However, if you’re using target to point to a specific tab/window, this will prevent that from working correctly. You can remove or change the default value by setting the attribute to an empty string or a value of your choice, respectively. string 'noreferrer noopener'
download Tells the browser to download the linked file as this filename. Only used when href is present. string | undefined -
form The “form owner” to associate the button with. If omitted, the closest containing form will be used instead. The value of this attribute must be an id of a form in the same document or shadow root as the button. string -
formAction
formaction 		Used to override the form owner’s action attribute. string -
formEnctype
formenctype 		Used to override the form owner’s enctype attribute. 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain' -
formMethod
formmethod 		Used to override the form owner’s method attribute. 'post' | 'get' -
formNoValidate
formnovalidate 		Used to override the form owner’s novalidate attribute. boolean -
formTarget
formtarget 		Used to override the form owner’s target attribute. '_self' | '_blank' | '_parent' | '_top' | string -
forDialog
for-dialog 		Used to connect this button to a dqialog on the page. Clicking the button will toggle the dialog’s visiblity string | undefined -
expanded if button is used to control another element on the page, such as an accordion or dialog, this state communicates whether the controlled element is expanded boolean false
validity Gets the validity state object - -
validationMessage Gets the validation message - -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Methods

Name Description Arguments
click() Simulates a click on the button. -
focus() Sets focus on the button. options: FocusOptions
blur() Removes focus from the button. -
checkValidity() Checks for validity but does not show a validation message. Returns true when valid and false when invalid. -
getForm() Gets the associated form, if one exists. -
reportValidity() Checks for validity and shows the browser’s validation message if the control is invalid. -
setCustomValidity() Sets a custom validation message. Pass an empty string to restore validity. message: string

Learn more about methods.

Parts

Name Description
base The component’s base wrapper.
prefix The container that wraps the prefix.
label The button’s label.
suffix The container that wraps the suffix.
caret The button’s caret icon, an <terra-icon> element.
spinner The spinner that shows when the button is in the loading state.

Learn more about customizing CSS parts.