# Chain Selector

> Network switcher with chain icons, active-chain indicator, per-row pending state and inline errors.

- Install: `npx shadcn@latest add @0xui/chain-selector`
- Registry JSON: https://0xui.io/r/chain-selector.json
- Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/chain-selector.tsx

Default,
  IconOnly,
  Dialog,
  GroupByNetwork,
  Branded,
} from "@/demos/chain-selector";

Shows the current chain and lets the user switch to any chain in your wagmi config. Comes as a popover (`ChainSelector`) and a dialog (`ChainSelectorDialog`). Both share the same props and behavior.

## Installation

```bash
npx shadcn@latest add @0xui/chain-selector
```

Requires the `@0xui` registry in `components.json` and a `<Web3Provider>` around your app. See [Installation](https://0xui.io/getting-started/installation.md).

## Usage

```tsx
import { ChainSelector } from "@/components/chain-selector";

<ChainSelector />;
```

Chains come from your wagmi config. There is nothing to pass in.

## Examples

### Icon only

The label is hidden visually but stays available as a tooltip and to screen readers.

```tsx
<ChainSelector iconOnly />
```

### Dialog

Better on small screens, or when the list of chains is long.

```tsx
import { ChainSelectorDialog } from "@/components/chain-selector";

<ChainSelectorDialog />;
```

### Grouped by network

Splits chains into Mainnet and Testnet tabs, based on `chain.testnet`.

```tsx
<ChainSelector groupByNetwork />
```

### Branded icons

```tsx
<ChainSelector variant="branded" />
```

## States

| State | What the user sees |
| --- | --- |
| Before hydration | A skeleton of the icon and name, so server HTML never shows wallet state and nothing moves when the chain appears. "Select Chain" for screen readers. |
| Idle | Current chain icon and name. In the list, the active chain has a checkmark and `aria-current`. |
| Switching | Spinner on the trigger and on the target row. The list is disabled until the wallet responds. |
| Cancelled | The user dismissed the wallet prompt. Muted "Request cancelled in wallet" note. |
| Error | Any other failure. The wallet's message is shown inline with `role="alert"`. |
| Wrong network | The wallet is on a chain your config doesn't include. The trigger reads "Wrong network" with a warning icon, and the list asks the user to pick a supported chain. |

Errors and the cancelled note clear when the selector is reopened.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"background" \| "branded" \| "mono"` | `"background"` | Chain icon style. |
| `monoColor` | `string` | — | Icon color. Only with `variant="mono"`. |
| `iconOnly` | `boolean` | `false` | Hide the visible label. It stays accessible. |
| `groupByNetwork` | `boolean` | `false` | Group chains into Mainnet / Testnet tabs. |
| `chainIcon` | `ComponentType<ChainIconProps> \| false` | `NetworkIcon` | Custom chain icon, or `false` to hide it. |
| `chevronIcon` | `ComponentType<{ className?: string }> \| false` | `ChevronDownIcon` | Custom chevron, or `false` to hide it. |
| `loaderIcon` | `ComponentType<{ className?: string }> \| false` | `Loader2Icon` | Custom spinner, or `false` to hide it. |
| `disableIcons` | `boolean` | `false` | Hide every icon. Overrides the icon props. |
| `chainMeta` | `(chain: Chain) => ReactNode` | — | Extra detail under each chain's name, e.g. `"~2s blocks"`. |
