> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt
> Use this file to discover all available pages before exploring further.

# React components

> Embed Hyperline checkout, customer portal, and payment method components directly in your React application with the official React SDK.

Hyperline provides built-in React components to:

* Display a customer's subscriptions
* Preview and update the payment method
* List and download invoices
* List and update billing information

<Frame caption="List and download invoices">
  <img width="50%" src="https://mintcdn.com/hyperline/8TZTJS2qOc6hY5Mm/images/api-reference/react/react4.png?fit=max&auto=format&n=8TZTJS2qOc6hY5Mm&q=85&s=6da8687123903a4f743996cbf5d8e8a9" style={{ margin: "auto" }} data-path="images/api-reference/react/react4.png" />
</Frame>

<Frame caption="Display active payment method">
  <img width="50%" src="https://mintcdn.com/hyperline/8TZTJS2qOc6hY5Mm/images/api-reference/react/react-payment-method.png?fit=max&auto=format&n=8TZTJS2qOc6hY5Mm&q=85&s=0b02448d2a879114d2c3a8f00c3f5daf" style={{ margin: "auto" }} data-path="images/api-reference/react/react-payment-method.png" />
</Frame>

This page assumes that you already have a basic working knowledge of [React](https://react.dev/) and that you have already set up a React project.

## Getting started

<Steps>
  <Step title="Install the dependency">
    Install the `@hyperline/react-components` NPM package.

    ```sh Install the package theme={null}
    npm install @hyperline/react-components
    ```
  </Step>

  <Step title="Create an auth token">
    To allow a customer to see their Hyperline data, you need to generate a unique authentication token on your server side. You can use the Hyperline API and the [create auth token endpoint](/api-reference/endpoints/integrations/create-component-token) for this.

    ```sh cURL theme={null}
    curl -X POST 'https://api.hyperline.co/v1/integrations/components/token' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer <API key>' \ # You can create an [api key here](https://app.hyperline.co/app/settings/api)
      -d '{ "customer_id": "<customer ID>" }'
    ```
  </Step>

  <Step title="Integrate the React components">
    Then, integrate the React components. You will most likely generate a new token every time your customer accesses the page.

    ```ts theme={null}
    import { Subscriptions, PaymentMethod } from "@hyperline/react-components";

    export default function HyperlineSubscriptions() {
      return (
        <Subscriptions
          options={{
            token: "<YOUR AUTH TOKEN>",
            mode: "production" // if you're using our sandbox, set "sandbox" here
            locale: "en" // optional
          }}
        />
      );
    }

    export default function HyperlinePaymentMethod() {
      return (
        <PaymentMethod
          options={{
            token: "<YOUR AUTH TOKEN>",
            mode: "production" // if you're using our sandbox, set "sandbox" here
            locale: "en" // optional
          }}
          onPaymentMethodCreated={() => do something} // optional, from 0.2.20
          onPaymentMethodDeleted={() => do something} // optional, from 0.2.20
        />
      );
    }
    ```
  </Step>
</Steps>

<Frame caption="Example of a subscription">
  <img width="50%" src="https://mintcdn.com/hyperline/8TZTJS2qOc6hY5Mm/images/api-reference/react/react1.png?fit=max&auto=format&n=8TZTJS2qOc6hY5Mm&q=85&s=60df922f44dac72ce02149760cd95c4d" style={{ margin: "auto" }} data-path="images/api-reference/react/react1.png" />
</Frame>

<Frame caption="Update billing info">
  <img width="50%" src="https://mintcdn.com/hyperline/8TZTJS2qOc6hY5Mm/images/api-reference/react/react-update-info.png?fit=max&auto=format&n=8TZTJS2qOc6hY5Mm&q=85&s=3a59ba6f1ad5db5e82dace6fa9c39740" style={{ margin: "auto" }} data-path="images/api-reference/react/react-update-info.png" />
</Frame>

## Components

### Subscriptions

List all active subscriptions

```tsx theme={null}
<Subscriptions
  options={{
    token: "<token>"
  }}
/>
```

### Subscription

Display a subscription by ID

```tsx theme={null}
<Subscription
  id="sub_xxxx"
  options={{
    token: "<token>"
  }}
/>
```

### InvoicesList

List and download all invoices and refunds

```tsx theme={null}
<InvoicesList
  options={{
    token: "<token>"
  }}
/>
```

### PaymentMethod

Display the current payment method, delete it if allowed, or add a new payment method

```tsx theme={null}
<PaymentMethod
  options={{
    token: "<token>"
  }}
/>
```

### CustomerBillingInfoForm

Display a form with all billing info, with an optional callback when the form has been successfully saved.

```tsx theme={null}
<CustomerBillingInfoForm
  onSuccess={() => {}}
  options={{
    token: "<token>"
  }}
/>
```

## Component options

When using the components, provide an `options` prop with the following parameters:

| Name | Description | Type | Default value | Required |
| - | - | - | - | - |
| token | The token specific to your customer | string | | ☑️ |
| mode | The Hyperline environment you are using | production \| sandbox | production | |
| appearance | Customize the appearance of the component | Object | | |

### Appearance

You can change the colors and fonts of the component.

```tsx theme={null}
<Subscriptions
  options={{
    token: "<token>",
    appearance: {
      variables: {
        borderRadius: "10px",
        colorBackground: "#000000",
        colorPrimary: "#e1e2f3",
        colorPrimaryHover: "#d0d1e5",
        colorPrimaryDisabled: "#667",
        colorBorder: "#445",
        colorText: "#f1f2f3",
        colorTextSecondary: "#dededf",
        fontFamily: "sacramento"
      },
      fonts: [
        {
          src: "url(https://fonts.gstatic.com/s/sacramento/v13/buEzpo6gcdjy0EiZMBUG4C0f_f5Iai0.woff2)",
          family: "sacramento"
        }
      ]
    }
  }}
/>
```

<Frame caption="Custom color">
  <img width="50%" src="https://mintcdn.com/hyperline/8TZTJS2qOc6hY5Mm/images/api-reference/react/react3.png?fit=max&auto=format&n=8TZTJS2qOc6hY5Mm&q=85&s=91274384b633343b3aeb127c5c3207d8" style={{ margin: "auto" }} data-path="images/api-reference/react/react3.png" />
</Frame>

### Variables

Use variables to customize all elements at once.

| Variable name | Description |
| - | - |
| `borderRadius` | Change the roundness of the elements: Buttons, tables, ... |
| `colorBackground` | Most elements have a transparent background. In other cases, you can customize the background color of the element |
| `colorPrimary` | Color used for buttons and accent text |
| `colorPrimaryHover` | Hover color for buttons |
| `colorPrimaryDisabled` | Color of disabled buttons |
| `colorBorder` | The color of all our regular borders |
| `colorText` | Default text color |
| `colorTextSecondary` | Text color of secondary text |
| `fontFamily` | Font used. If you need to import a font, see the next section |

### Fonts

Set your application's font.

* `src` Url of the font file
* `family` Name of the font. This is the name you'll use for the `fontFamily` variable

```ts theme={null}
<Subscriptions
  options={{
    fonts: [
      {
        src: "url(https://fonts.gstatic.com/s/sacramento/v13/buEzpo6gcdjy0EiZMBUG4C0f_f5Iai0.woff2)",
        family: "sacramento"
      }
    ]
  }}
/>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.