# ProviderButton

A full-width outline button that starts sign-in with a third-party provider. While pending, a spinner replaces the icon and the labels stay put. `ProviderButtonGroup` lays several out and picks which label each shows.

## Use for

- a sign in with Google, GitHub or another provider button
- a row or stack of social sign-in buttons
- marking the provider used last

## Practices

- Do: Pass both `longLabel` and `shortLabel`. The group picks one from how many buttons share a row.
- Do: Make each `ProviderButton` a direct child of `ProviderButtonGroup`; put the last-used one in `lastUsed`.
- Do: Disable the group while any provider is pending, so the other buttons wait.
- Do: Pass a localized `pendingLabel`. The default is English.
- Don't: Use `Button` or `SubmitButton` for a provider sign-in.

## API reference

### ProviderButton

A `Button` with the icon, both labels and an optional badge. Takes every `Button` prop but `shape`. While `isPending` it goes inert and `aria-busy`, and carries `data-pending`.

Slot: `cl-button`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `React.ReactNode` |  | The provider's icon. The spinner takes its place while pending. |
| `longLabel` | `string` |  | The full call to action, such as `Continue with Google`. Also the accessible name. |
| `shortLabel` | `string` |  | The provider's name, shown when two buttons share a row. |
| `badge` | `string` |  | Short text on the top edge, such as `Last used`. Added to the accessible name. |
| `isPending` | `boolean` | `false` | Marks the sign-in as running. |
| `pendingLabel` | `string` | `'pending'` | The spinner name, added to the accessible name while pending. |
| `spinDelay` | `SpinDelayOptions` |  | When the spinner shows and how long it stays. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | `xs`, `sm`, `md` or `lg`. |

### ProviderButtonGroup

A `div` that lays out its `ProviderButton` children and passes `disabled` down to them.

Slot: `cl-provider-button-group`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` | `'inline' \| 'stacked'` | `'inline'` | `inline` fills rows of up to five, showing the long label for one button, the short label for two, the icon alone for three or more. `stacked` gives each its own row with the long label. |
| `disabled` | `boolean` | `false` | Disables every button. A pending button keeps full opacity. |
| `lastUsed` | `React.ReactNode` |  | The provider used last, on its own row above the others with its long label. |

## Examples

### A group

```tsx
<ProviderButtonGroup disabled={isBusy}>
  <ProviderButton icon={<GoogleIcon />} longLabel='Continue with Google' shortLabel='Google' />
  <ProviderButton icon={<GitHubIcon />} longLabel='Continue with GitHub' shortLabel='GitHub' />
</ProviderButtonGroup>
```

## Related

- [Button](/docs/components/button.md)
- [useSpinDelay](/docs/hooks/use-spin-delay.md)
