---
title: Host connection
description: Compose DomainKit connection state into an existing product surface while retaining the packaged controller and dialog.
---

Use the connection controller and semantic parts when your application already owns the surrounding
card, navigation, provider copy, or action layout.

<ReactExample story="host-connection" />

## Installation

```package-install
@domainkit/react domainkit effect @effect/atom-react react react-dom
```

## Usage

Create one controller for the domain and derive the visible surface from its tagged state. Keep the
controller and the rendered dialog together so pending OAuth or token submissions cannot diverge
from the displayed state.

```tsx
const controller = Connection.useController(domain);

return (
  <Connection.Root status={controller.state._tag}>
    <Connection.Status state={controller.state} />
  </Connection.Root>
);
```

## Composition contract

- `useController` owns the connection model and commands for one domain.
- `Root` exposes the state through `data-state` and accepts host styling.
- `Status` renders the current human-readable outcome.
- `ConnectTrigger` and `Dialog` compose with Base UI dialog state.
- `RetryAction` follows the failure’s explicit retry policy.

The host still owns authenticated endpoints, tenant checks, credential storage, connection
persistence, and OAuth callback routes.

## Accessibility

Use a real button for the connection trigger. If you replace its visible text, include the provider
name in the accessible label. Preserve dialog focus management and the disabled state while a
submission or redirect is pending.

## API reference

### `Connection.Root`

| Prop | Type | Default | Description |
| - | - | - | - |
| `status?` | `Connection.State["_tag"]` | `"Loading"` | State tag exposed through data-state and state-aware styling. |

### `Connection.Status`

| Prop | Type | Default | Description |
| - | - | - | - |
| `state` | `Connection.State` | - | Connection state used to derive the visible status message. |

### `Connection.ConnectTrigger`

| Prop | Type | Default | Description |
| - | - | - | - |
| `children?` | `ReactNode` | - | Optional custom trigger content; the default includes the provider mark and label. |
| `provider` | `Provider.Provider` | - | Provider descriptor whose authentication dialog the trigger opens. |

### `Connection.Dialog`

| Prop | Type | Default | Description |
| - | - | - | - |
| `controller` | `Connection.Controller` | - | Controller that owns connection commands and state. |
| `snapshot` | `Disconnected` | - | Disconnected provider snapshot used to render authorization options. |

See [Composition](/docs/react/composition) for the shared part-prop and state-aware styling model.