# Button component for Stripe Apps

Use buttons to allow users to take actions, or to direct a user's attention or warn them of outcomes.

# v8

> This is a v8 for when app-sdk-version is 8. View the full page at https://docs.stripe.com/stripe-apps/components/button?app-sdk-version=8.

To add the `Button` component to your app:

```js
import {Button} from '@stripe/ui-extension-sdk/ui';
```

There are multiple button types available:

### Button props

| Property    | Type                                                                                                                                         |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`  | (Required)
  `React.ReactNode`

  The contents of the component.                                                                             |
| `css`       | (Optional)
  `CSS | undefined`

  Related types: [CSS](https://docs.stripe.com/stripe-apps/components/button.md#css).                        |
| `disabled`  | (Optional)
  `boolean | undefined`

  Whether the action is disabled.                                                                        |
| `href`      | (Optional)
  `string | undefined`

  Native `href` attribute.                                                                                |
| `onPress`   | (Optional)
  `((event: PressEvent) => void) | undefined`

  Handler that is called when the press is released over the target.               |
| `size`      | (Optional)
  `("small" | "medium" | "large") | undefined`

  The size of the component.                                                      |
| `target`    | (Optional)
  `("_self" | "_blank" | "_top" | "_parent") | undefined`

  Where to display the linked URL, as the name for a browsing context. |
| `type`      | (Optional)
  `("primary" | "secondary" | "destructive") | undefined`

  The type of the `Button`.                                            |
| `className` | (Optional)(Deprecated)
  `string | undefined`                                                                                                |

### CSS

| Property | Type                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `alignX` | (Optional)
  `("start" | "center" | "end" | "stretch") | undefined`

  Horizontal alignment. See [Layout properties](https://docs.stripe.com/stripe-apps/style.md#layout-properties) for details.                                                                                                                                                                                                                        |
| `width`  | (Optional)
  `(number | "auto" | "fill" | "min" | "max" | "fit" | "1/2" | "1/3" | "2/3" | "1/4" | "2/4" | "3/4" | "1/5" | "2/5" | "3/5" | "4/5" | "1/6" | "2/6" | "3/6" | "4/6" | "5/6" | "1/12" | "2/12" | "3/12" | "4/12" | "5/12" | "6/12" | "7/12" | "8/12" | "9/12" | "10/12" | "11/12") | undefined`

  The width of the component. See [Sizing](https://docs.stripe.com/stripe-apps/style.md#sizing) for details. |

## Content guidelines

### Use the {verb} + {noun} formula for labels

For example, **Update customer**. It’s acceptable to break this pattern in the case of common actions like **Done**, **Close**, **Cancel**, **Add**, or **Delete**.

### Be as descriptive as possible

When a button performs an action or navigates the user to a location, try to name that action or location within the label.

### Use sentence case

This applies for most cases except proper nouns and phrases.

### Avoid punctuation

Avoid periods, exclamation points, and question marks.

### Use second person

When referring to the user within a button or link, always use second person personal pronouns. Example: **Post your status**.

## Primary buttons

Primary buttons initiate the primary action of any given page or flow. Avoid having more than one primary button available to the user at a given time.

## Secondary buttons

Secondary buttons are the default and most common buttons in product interfaces. In general, use the secondary style for buttons that aren’t for primary actions.

## Destructive buttons

Use destructive buttons exclusively for actions that result in the destruction of any object or data.

## Button sizes

Buttons are available in three sizes, which determine the height of the element. Buttons can be as wide as needed to fill their container.

- You can use small buttons in contexts where space is limited or to match the size of other, small text such as legal terms, and so on.
- Medium is the default size for buttons.
- You can use large buttons in contexts where a call to action (CTA) needs increased prominence.

## Disabled buttons

## Icons in buttons

Use an [icon](https://docs.stripe.com/stripe-apps/components/icon.md) inside of a button:

## Full-width buttons

Create a full-width `Button` component using the `css` prop:

## Opening links in new tabs


# v9

> This is a v9 for when app-sdk-version is 9. View the full page at https://docs.stripe.com/stripe-apps/components/button?app-sdk-version=9.

To add the `Button` component to your app:

```js
import {Button} from '@stripe/ui-extension-sdk/ui';
```

There are multiple button types available:

### Button props

| Property   | Type                                                                                                                                                                                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | (Required)
  `React.ReactNode`

  The contents of the component.                                                                                                                                                                                     |
| `css`      | (Optional)
  `CSS | undefined`

  Related types: [CSS](https://docs.stripe.com/stripe-apps/components/button.md#css).                                                                                                                                |
| `disabled` | (Optional)
  `boolean | undefined`

  Whether the action is disabled.                                                                                                                                                                                |
| `href`     | (Optional)
  `((string | RouteDescriptor) | undefined) | undefined`

  A native `href` attribute or a dashboard route to navigate to.

  Related types: [RouteDescriptor](https://docs.stripe.com/stripe-apps/components/button.md#routedescriptor). |
| `onPress`  | (Optional)
  `((event: PressEvent) => void) | undefined`

  Handler that is called when the press is released over the target.                                                                                                                       |
| `pending`  | (Optional)
  `boolean | undefined`

  Sets the visual style to pending and functionally disables the `Button`.                                                                                                                                       |
| `size`     | (Optional)
  `("small" | "medium" | "large") | undefined`

  The size of the component.                                                                                                                                                              |
| `target`   | (Optional)
  `("_self" | "_blank" | "_top" | "_parent") | undefined`

  Where to display the linked URL, as the name for a browsing context.                                                                                                         |
| `type`     | (Optional)
  `("primary" | "secondary" | "destructive") | undefined`

  The type of the `Button`.                                                                                                                                                    |

### CSS

| Property | Type                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `alignX` | (Optional)
  `("start" | "center" | "end" | "stretch") | undefined`

  Horizontal alignment. See [Layout properties](https://docs.stripe.com/stripe-apps/style.md#layout-properties) for details.                                                                                                                                                                                                                        |
| `width`  | (Optional)
  `(number | "auto" | "fill" | "min" | "max" | "fit" | "1/2" | "1/3" | "2/3" | "1/4" | "2/4" | "3/4" | "1/5" | "2/5" | "3/5" | "4/5" | "1/6" | "2/6" | "3/6" | "4/6" | "5/6" | "1/12" | "2/12" | "3/12" | "4/12" | "5/12" | "6/12" | "7/12" | "8/12" | "9/12" | "10/12" | "11/12") | undefined`

  The width of the component. See [Sizing](https://docs.stripe.com/stripe-apps/style.md#sizing) for details. |

### RouteDescriptor

This is a union type. It can be one of: [BalanceOverviewRoute](https://docs.stripe.com/stripe-apps/components/button.md#balanceoverviewroute), [BillingRoute](https://docs.stripe.com/stripe-apps/components/button.md#billingroute), [CustomersRoute](https://docs.stripe.com/stripe-apps/components/button.md#customersroute), [CustomerDetailsRoute](https://docs.stripe.com/stripe-apps/components/button.md#customerdetailsroute), [DashboardRoute](https://docs.stripe.com/stripe-apps/components/button.md#dashboardroute), [FullPageRoute](https://docs.stripe.com/stripe-apps/components/button.md#fullpageroute), [InvoiceDetailsRoute](https://docs.stripe.com/stripe-apps/components/button.md#invoicedetailsroute), [InvoicesRoute](https://docs.stripe.com/stripe-apps/components/button.md#invoicesroute), [OnboardingRoute](https://docs.stripe.com/stripe-apps/components/button.md#onboardingroute), [PaymentDetailsRoute](https://docs.stripe.com/stripe-apps/components/button.md#paymentdetailsroute), [PaymentReviewDetailsRoute](https://docs.stripe.com/stripe-apps/components/button.md#paymentreviewdetailsroute), [PaymentsRoute](https://docs.stripe.com/stripe-apps/components/button.md#paymentsroute), [ProductDetailsRoute](https://docs.stripe.com/stripe-apps/components/button.md#productdetailsroute), [ProductsRoute](https://docs.stripe.com/stripe-apps/components/button.md#productsroute), [ReportsHubRoute](https://docs.stripe.com/stripe-apps/components/button.md#reportshubroute), [RevenueRecognitionRoute](https://docs.stripe.com/stripe-apps/components/button.md#revenuerecognitionroute), [ShippingRateDetailsRoute](https://docs.stripe.com/stripe-apps/components/button.md#shippingratedetailsroute), [ShippingRatesRoute](https://docs.stripe.com/stripe-apps/components/button.md#shippingratesroute), [SubscriptionDetailsRoute](https://docs.stripe.com/stripe-apps/components/button.md#subscriptiondetailsroute), [SubscriptionsRoute](https://docs.stripe.com/stripe-apps/components/button.md#subscriptionsroute), [TaxReportingLocationsRoute](https://docs.stripe.com/stripe-apps/components/button.md#taxreportinglocationsroute), [TaxReportingRoute](https://docs.stripe.com/stripe-apps/components/button.md#taxreportingroute).

### BalanceOverviewRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"balanceOverview"`                                                                                                       |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### BillingRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"billing"`                                                                                                               |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### CustomersRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"customers"`                                                                                                             |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### CustomerDetailsRoute

| Property    | Type                                                                                                                                    |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"customerDetails"`                                                                                                        |
| `params`    | (Required)
  `Params`

  Related types: [Params](https://docs.stripe.com/stripe-apps/components/button.md#customerdetailsroute-params). |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop.  |

### CustomerDetailsRoute Params

| Property     | Type                                             |
| ------------ | ------------------------------------------------ |
| `customerId` | (Required)
  `string`

  The id of the customer. |

### DashboardRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"dashboard"`                                                                                                             |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### FullPageRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"fullPage"`                                                                                                              |
| `params`    | (Required)
  `Params`

  Related types: [Params](https://docs.stripe.com/stripe-apps/components/button.md#fullpageroute-params).       |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### FullPageRoute Params

| Property | Type                                                                              |
| -------- | --------------------------------------------------------------------------------- |
| `appId`  | (Required)
  `string`

  The id of the app.                                       |
| `tabId`  | (Optional)
  `string | undefined`

  The id of the tab that needs to be selected. |

### InvoiceDetailsRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"invoiceDetails"`                                                                                                        |
| `params`    | (Required)
  `Params`

  Related types: [Params](https://docs.stripe.com/stripe-apps/components/button.md#invoicedetailsroute-params). |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### InvoiceDetailsRoute Params

| Property    | Type                                            |
| ----------- | ----------------------------------------------- |
| `invoiceId` | (Required)
  `string`

  The id of the invoice. |

### InvoicesRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"invoices"`                                                                                                              |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### OnboardingRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"onboarding"`                                                                                                            |
| `params`    | (Required)
  `Params`

  Related types: [Params](https://docs.stripe.com/stripe-apps/components/button.md#onboardingroute-params).     |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### OnboardingRoute Params

| Property | Type                                        |
| -------- | ------------------------------------------- |
| `appId`  | (Required)
  `string`

  The id of the app. |

### PaymentDetailsRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"paymentDetails"`                                                                                                        |
| `params`    | (Required)
  `Params`

  Related types: [Params](https://docs.stripe.com/stripe-apps/components/button.md#paymentdetailsroute-params). |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### PaymentDetailsRoute Params

| Property    | Type                                            |
| ----------- | ----------------------------------------------- |
| `paymentId` | (Required)
  `string`

  The id of the payment. |

### PaymentReviewDetailsRoute

| Property    | Type                                                                                                                                         |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"paymentReviewDetails"`                                                                                                        |
| `params`    | (Required)
  `Params`

  Related types: [Params](https://docs.stripe.com/stripe-apps/components/button.md#paymentreviewdetailsroute-params). |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop.       |

### PaymentReviewDetailsRoute Params

| Property    | Type                                            |
| ----------- | ----------------------------------------------- |
| `paymentId` | (Required)
  `string`

  The id of the payment. |

### PaymentsRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"payments"`                                                                                                              |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### ProductDetailsRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"productDetails"`                                                                                                        |
| `params`    | (Required)
  `Params`

  Related types: [Params](https://docs.stripe.com/stripe-apps/components/button.md#productdetailsroute-params). |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### ProductDetailsRoute Params

| Property    | Type                                            |
| ----------- | ----------------------------------------------- |
| `productId` | (Required)
  `string`

  The id of the product. |

### ProductsRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"products"`                                                                                                              |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### ReportsHubRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"reportsHub"`                                                                                                            |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### RevenueRecognitionRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"revenueRecognition"`                                                                                                    |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### ShippingRateDetailsRoute

| Property    | Type                                                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"shippingRateDetails"`                                                                                                        |
| `params`    | (Required)
  `Params`

  Related types: [Params](https://docs.stripe.com/stripe-apps/components/button.md#shippingratedetailsroute-params). |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop.      |

### ShippingRateDetailsRoute Params

| Property         | Type                                                  |
| ---------------- | ----------------------------------------------------- |
| `shippingRateId` | (Required)
  `string`

  The id of the shipping rate. |

### ShippingRatesRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"shippingRates"`                                                                                                         |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### SubscriptionDetailsRoute

| Property    | Type                                                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"subscriptionDetails"`                                                                                                        |
| `params`    | (Required)
  `Params`

  Related types: [Params](https://docs.stripe.com/stripe-apps/components/button.md#subscriptiondetailsroute-params). |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop.      |

### SubscriptionDetailsRoute Params

| Property         | Type                                                 |
| ---------------- | ---------------------------------------------------- |
| `subscriptionId` | (Required)
  `string`

  The id of the subscription. |

### SubscriptionsRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"subscriptions"`                                                                                                         |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### TaxReportingLocationsRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"taxReportingLocations"`                                                                                                 |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

### TaxReportingRoute

| Property    | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | (Required)
  `"taxReporting"`                                                                                                          |
| `envParams` | (Optional)
  `{     [x: string]: string; } | undefined`

  Query params that are passed to Extension views via the `environment` prop. |

## Content guidelines

### Use the {verb} + {noun} formula for labels

For example, **Update customer**. It’s acceptable to break this pattern in the case of common actions like **Done**, **Close**, **Cancel**, **Add**, or **Delete**.

### Be as descriptive as possible

When a button performs an action or navigates the user to a location, try to name that action or location within the label.

### Use sentence case

This applies for most cases except proper nouns and phrases.

### Avoid punctuation

Avoid periods, exclamation points, and question marks.

### Use second person

When referring to the user within a button or link, always use second person personal pronouns. Example: **Post your status**.

## Primary buttons

Primary buttons initiate the primary action of any given page or flow. Avoid having more than one primary button available to the user at a given time.

## Secondary buttons

Secondary buttons are the default and most common buttons in product interfaces. In general, use the secondary style for buttons that aren’t for primary actions.

## Destructive buttons

Use destructive buttons exclusively for actions that result in the destruction of any object or data.

## Button sizes

Buttons are available in three sizes, which determine the height of the element. Buttons can be as wide as needed to fill their container.

- You can use small buttons in contexts where space is limited or to match the size of other, small text such as legal terms, and so on.
- Medium is the default size for buttons.
- You can use large buttons in contexts where a call to action (CTA) needs increased prominence.

## Disabled buttons

## Icons in buttons

Use an [icon](https://docs.stripe.com/stripe-apps/components/icon.md) inside of a button:

## Full-width buttons

Create a full-width `Button` component using the `css` prop:

## Opening links in new tabs

## Pending buttons


## See also

- [Design patterns to follow](https://docs.stripe.com/stripe-apps/patterns.md)
- [Style your app](https://docs.stripe.com/stripe-apps/style.md)
- [UI testing](https://docs.stripe.com/stripe-apps/ui-testing.md)