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

# Provider component

> Render Primer components outside the primer-checkout element.

## \<primer-provider>

Makes a checkout's payment session available to Primer components rendered outside `<primer-checkout>`. Use it when your layout places payment UI elsewhere on the page — a fixed footer, a separate column, or a dialog that renders into `document.body`.

Primer components only work inside `<primer-checkout>`. A component placed anywhere else renders nothing, and the browser console shows a warning naming `<primer-provider>`. Wrap it in a `<primer-provider>` that references the checkout by its `id`.

## Quick reference

| | |
| - | - |
| **Parent** | Anywhere in the same document as `<primer-checkout>` |
| **Attributes** | `checkout-id` (required) |
| **Slots** | Default slot |

***

## Examples

### Basic usage

```html theme={"dark"}
<primer-checkout id="my-checkout" client-token="your-token"></primer-checkout>

<!-- Elsewhere on the page -->
<primer-provider checkout-id="my-checkout">
  <primer-card-form></primer-card-form>
</primer-provider>
```

### Inside a React portal

Most component libraries render a dialog into `document.body`, outside the checkout. Wrap the dialog content in a provider:

```tsx theme={"dark"}
import { createPortal } from 'react-dom';

<primer-checkout id="my-checkout" client-token={clientToken}></primer-checkout>

{createPortal(
  <primer-provider checkout-id="my-checkout">
    <primer-card-form></primer-card-form>
  </primer-provider>,
  document.body,
)}
```

### Showing a success message

The provider renders nothing once the payment succeeds. Show your confirmation outside it:

```javascript theme={"dark"}
const checkout = document.getElementById('my-checkout');

checkout.addEventListener('primer:payment-success', () => {
  document.getElementById('order-confirmation').hidden = false;
});
```

***

## Attributes

| Attribute | Type | Required | Description |
| - | - | - | - |
| `checkout-id` | `string` | Yes | The `id` of the `<primer-checkout>` element whose session to use |

***

## States

The provider renders its content only while the payment session is active, the same as the `payments` slot of `<primer-main>`.

| State | Content rendered |
| - | - |
| **Loading** | Nothing |
| **Ready** | Yes |
| **Processing** | Yes |
| **Success** | Nothing |
| **Error** (SDK initialization failed) | Nothing |

This prevents a second payment from being started after the first one succeeds. Everything inside the provider is hidden in these states, including your own markup.

***

## Usage guidelines

### Do

* Give `<primer-checkout>` an `id` and pass the same value to `checkout-id`
* Render `<primer-checkout>` before the provider. If the checkout is not in the page when the provider connects, the provider logs an error and does not retry
* Place success and error messages outside the provider, and show them using `primer:payment-success` or `primer:state-change`

### Don't

* Don't place `<primer-checkout>` inside another element's shadow DOM — the provider looks it up with `document.getElementById`, which does not search shadow roots
* Don't use a provider inside `<primer-checkout>` — components there already have access to the session

***

## Troubleshooting

| Console message | Cause |
| - | - |
| `<primer-card-form> is rendered outside <primer-checkout>…` | The component is outside the checkout without a provider |
| `primer-provider requires a checkout-id attribute…` | The `checkout-id` attribute is missing or empty |
| `primer-provider could not find a primer-checkout element with id "…"` | No element has that `id`, the element with that `id` is not a `<primer-checkout>`, or the checkout was not in the page yet when the provider connected |

***

## See also

<CardGroup cols={2}>
  <Card title="primer-checkout" icon="cube" href="/docs/sdk/primer-checkout-web/components/primer-checkout">
    The component that owns the payment session
  </Card>

  <Card title="primer-main" icon="layer-group" href="/docs/sdk/primer-checkout-web/components/primer-main">
    Slots and state handling inside the checkout
  </Card>

  <Card title="Layout customization" icon="table-layout" href="/docs/checkout/primer-checkout/build-your-ui/layout-customization">
    Slot usage guide
  </Card>
</CardGroup>


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