CustomDomainConnect

Full flow (simulated checks)

import { useState } from 'react';
import { CustomDomainConnect, type CustomDomainRecord, type CustomDomainStatus } from '@rookcom/monarch-react/patterns';

const RECORDS: CustomDomainRecord[] = [
  {
    type: 'CNAME',
    name: 'help',
    value: 'pages.example.net',
    purpose: 'Points your address to the page',
  },
  {
    type: 'TXT',
    name: '_verify.help',
    value: 'verify=4f1c9a2e7b',
    purpose: 'Proves you own the domain',
    ttl: 'Auto',
  },
];

function FlowDemo() {
  const [status, setStatus] = useState<CustomDomainStatus>('pending');
  const [checks, setChecks] = useState(0);
  const wait = () => new Promise((r) => setTimeout(r, 900));
  return (
    <CustomDomainConnect
      requireSubdomain
      inputDescription="The address visitors will type, such as help.example.com."
      status={status}
      records={RECORDS.map((r, i) => (checks > 0 ? { ...r, found: i === 0 || checks > 1 } : r))}
      onConnect={wait}
      onVerify={async () => {
        await wait();
        setChecks((c) => c + 1);
        setStatus(checks > 0 ? 'active' : 'failed');
      }}
      failureReason="The TXT record was not found yet. DNS changes can take a while to appear."
      onRemove={async () => {
        await wait();
        setStatus('pending');
        setChecks(0);
      }}
      onDomainChange={(d) => {
        if (d === null) setStatus('pending');
      }}
    />
  );
}

<FlowDemo />

Usage examples

Pending, with records and provider hints

import { CustomDomainConnect, type CustomDomainRecord } from '@rookcom/monarch-react/patterns';

const RECORDS: CustomDomainRecord[] = [
  {
    type: 'CNAME',
    name: 'help',
    value: 'pages.example.net',
    purpose: 'Points your address to the page',
  },
  {
    type: 'TXT',
    name: '_verify.help',
    value: 'verify=4f1c9a2e7b',
    purpose: 'Proves you own the domain',
    ttl: 'Auto',
  },
];

<CustomDomainConnect
  defaultDomain="help.example.com"
  status="pending"
  onConnect={() => {}}
  onVerify={() => {}}
  onRemove={() => {}}
  records={[
    { ...(RECORDS[0] as CustomDomainRecord), found: true },
    { ...(RECORDS[1] as CustomDomainRecord), found: false },
  ]}
  lastChecked="Checked 2 minutes ago"
  providerHints={[
    {
      id: 'generic',
      label: 'Most providers',
      steps: [
        'Open the DNS settings for example.com.',
        'Add each record above with its exact type, name and value.',
        'Save, then come back and verify.',
      ],
    },
  ]}
/>

Failed with a reason

import { CustomDomainConnect, type CustomDomainRecord } from '@rookcom/monarch-react/patterns';

const RECORDS: CustomDomainRecord[] = [
  {
    type: 'CNAME',
    name: 'help',
    value: 'pages.example.net',
    purpose: 'Points your address to the page',
  },
  {
    type: 'TXT',
    name: '_verify.help',
    value: 'verify=4f1c9a2e7b',
    purpose: 'Proves you own the domain',
    ttl: 'Auto',
  },
];

<CustomDomainConnect
  defaultDomain="status.example.org"
  status="failed"
  failureReason="status.example.org points to another host. Change the CNAME value to pages.example.net."
  onConnect={() => {}}
  onVerify={() => {}}
  records={RECORDS.slice(0, 1).map((r) => ({ ...r, name: 'status', found: false }))}
/>

Active

import { CustomDomainConnect, type CustomDomainRecord } from '@rookcom/monarch-react/patterns';

const RECORDS: CustomDomainRecord[] = [
  {
    type: 'CNAME',
    name: 'help',
    value: 'pages.example.net',
    purpose: 'Points your address to the page',
  },
  {
    type: 'TXT',
    name: '_verify.help',
    value: 'verify=4f1c9a2e7b',
    purpose: 'Proves you own the domain',
    ttl: 'Auto',
  },
];

<CustomDomainConnect
  defaultDomain="book.example.com"
  status="active"
  onConnect={() => {}}
  onRemove={() => {}}
  records={RECORDS}
/>

Purpose

One flow for every product that serves a page on the customer’s own domain (support pages, booking pages, status pages, careers pages). It handles the steps, syntax checking, copyable records and status; the product runs the DNS checks. Import from @rookcom/monarch-react/patterns.

Use when

A customer points their own domain or subdomain at a page the product hosts.
The product gives DNS records to add and can check them on request or on a timer.

Avoid when

Showing a single value to copy, such as an API key or webhook URL: use CopyField or SecretField.
Picking a sub-path or slug on the product’s own domain: use an Input with a prefix.

Design principles

Four plain steps (Domain, DNS records, Verify, Live) shown with Stepper, so people know how far along they are.
Mistakes are caught before the network: what people paste (https://, paths, ports, capitals, a trailing dot) is cleaned up, and anything still not a host name is explained.
Every record value is a CopyField, so nothing is retyped by hand.
No provider copy is built in. Menus at DNS providers change, so the product passes provider hints it maintains.
Status is text and a badge, never colour alone; the failure reason is the product’s own words.

API reference

import { CustomDomainConnect, domainSyntaxError, normalizeDomain } from '@rookcom/monarch-react/patterns';

Export	Kind	Rendering	Root class
`CustomDomainConnect`	component	client	`.mn-custom-domain-connect`
`domainSyntaxError`	utility	client	–
`normalizeDomain`	utility	client	–

Renders a <section> (ref) with data-step set to enter, pending, verifying, active or failed.

onConnect(domain) receives the normalised domain; reject with an Error to show its message under the field. onVerify() and onRemove() may return promises.

domain / defaultDomain / onDomainChange hold the connected domain (null before connecting and after removal). status comes from the product.

normalizeDomain(input) and domainSyntaxError(input, { requireSubdomain }) are exported for server-side reuse.

Generated from the TypeScript declarations of packages/react/src/patterns/technical/custom-domain-connect.

Properties