# Custom domains

<div class="doc-callout doc-callout--info">
  <strong>Tip</strong>: Verify DNS first, then pick a home page. Most “doesn’t work” issues are missing TXT/CNAME or unverified status.
</div>

## Overview

A **custom domain** serves your **link pages** under a hostname you control (for example `links.yourbrand.com`) instead of only the default app host. You can attach **multiple pages** to one domain and designate a **home page**—the page shown when visitors open the root URL (`https://your-domain/`).

## How it works

1. Add the domain in the OnLynk dashboard.
2. OnLynk prepares your domain connection so it can be verified and served securely.
3. You add the required **DNS records** at your registrar (typically a **CNAME** and a **TXT** verification record).
4. Run **Verify** so OnLynk can confirm DNS and TLS; the domain moves to a **verified** state when checks pass.
5. Attach pages to the domain and optionally set which page is the **home** page for the apex or configured host.

## Prerequisites

- Your plan must include **custom domain** quota (`customDomains`).
- Use a valid DNS hostname; invalid names are rejected.
- Domains containing **`onlynk.me`** are not allowed (use a domain you own).

## DNS records (typical)

The dashboard shows the exact values for your domain. In general:

### CNAME

- **Type:** `CNAME`
- **Name / host:** As shown (often your subdomain, e.g. `www.example.com`)
- **Target / value:** `customers.onlynk.me` (confirm in UI)

### TXT (verification)

- **Type:** `TXT`
- **Name:** `_cf-custom-hostname.<your-domain>` (or as shown)
- **Value:** The verification string OnLynk displays—copy it exactly.

Propagation can take from minutes to **24 hours** depending on your DNS provider.

## Step-by-step

### Add and verify

1. Open **Domains** → **Add domain**.
2. Enter the domain, connect at least one page, and optionally set a **home page**.
3. Add DNS records at your registrar, then click **Verify**.
4. If TLS is not ready yet, status may stay **pending**; retry after DNS propagates.

### Manage pages on the domain

From the domain screen you can:

- Attach or detach pages from the **available pages** list
- Choose which connected page is the **home** page for that domain

Only one page should act as the home page at a time; the product keeps that association consistent when you change it.

## Limitations

- Domain count is limited by your plan.
- Moving a page between domains changes which hostname serves it—plan updates accordingly.

## FAQ

### Domain stuck in “pending”

Confirm the **CNAME** targets `customers.onlynk.me` (or the value shown), the **TXT** record matches exactly, and wait for DNS propagation.

### “Domain cannot contain onlynk.me”

Use a domain you control; that pattern is blocked by policy.