Skip to content
DomainKit
Esc
↑↓navigate↵open⌘Jpreview
On this page

Connection

Connect a customer domain to a supported DNS provider through your application’s authenticated, host-owned transport and persistence boundary.

Connection.Flow renders provider discovery, authorization choices, retry states, and attachment over the host-owned Transport. It does not put provider credentials in the browser.

import { Connection } from "@domainkit/react";

export function ConnectDomain() {
  return <Connection.Flow domain="mail.example.com" />;
}

Installation

npm install @domainkit/react domainkit effect @effect/atom-react react react-dom
pnpm add @domainkit/react domainkit effect @effect/atom-react react react-dom
yarn add @domainkit/react domainkit effect @effect/atom-react react react-dom
bun add @domainkit/react domainkit effect @effect/atom-react react react-dom

Import the default styles once in your application entry point:

import "@domainkit/react/styles.css";

Usage

Render the flow inside the DomainKit.Root that provides your transport, theme, messages, and provider marks.

import { Connection, DomainKit } from "@domainkit/react";

<DomainKit.Root transport={transportLayer}>
  <Connection.Flow domain="mail.example.com" />
</DomainKit.Root>;

The transport endpoint must authenticate the user, resolve tenant policy, keep credentials on the server, and persist connection and domain-attachment state. See Transport for the request boundary.

States

State Meaning
Disconnected A provider can be selected or an existing authorization can be reused.
Submitting The host transport is processing a token or attachment request.
Redirecting The browser is leaving for provider authorization.
Connected The host returned an active connection and domain attachment.
Detaching A disconnect request is in progress.
Failure The operation failed with an explicit retry policy.

Composition

Use Connection.useController(domain) when the packaged flow does not match your product surface. Compose Root, Status, ConnectTrigger, Dialog, and RetryAction around the same controller. The Host connection page shows that integration level.

Accessibility

Connection.Dialog uses dialog semantics and returns focus to its trigger. Keep a visible trigger label that names the provider, and do not suppress failure text when applying custom styles.

API reference

Connection.Flow

PropType
domainstring

Domain whose provider connection the flow manages.

Typestring

Connection.Dialog

PropType
controllerConnection.Controller

Controller that owns connection commands and state.

TypeConnection.Controller
snapshotDisconnected

Disconnected provider snapshot used to render authorization options.

TypeDisconnected

Connection.DisconnectDialog

PropType
connectionTransport.Connected

Connected domain attachment to disconnect.

TypeTransport.Connected
controllerConnection.Controller

Controller that performs the detach operation.

TypeConnection.Controller
onOpenChange?(open: boolean) => void

Called when the dialog's open state changes.

Type(open: boolean) => void
open?boolean

Controlled open state. Omit it to use the dialog's internal state.

Typeboolean
trigger?ReactElement | null

Optional trigger element. Pass null to render no trigger.

TypeReactElement | null

For the complete namespace inventory and shared runtime contracts, see the React API reference.

Was this page helpful?