# Connect panel

> Page: https://docs.flung.dev/reference/connect. Index of every page: https://docs.flung.dev/llms.txt

`@flung.dev/connect` gives your page `<flung-connect>`, a panel where people connect, reconnect and disconnect their social accounts, and `<FlungConnect>` for React. It takes a connect token your server makes, never an API key.

## TL;DR

| Question | Answer |
|---|---|
| How do I install it? | `npm install @flung.dev/connect` |
| Which version is this page for? | `0.1.1` |
| What does it need? | A connect token from `POST /v1/connect-tokens`, made on your server for your page's origin. See [Authentication](https://docs.flung.dev/authentication.md). |
| What does it depend on? | Nothing at run time. React is an optional peer, for the React component. |
| Which entry points are there? | `@flung.dev/connect/register` registers the element, `@flung.dev/connect/react` is the React component, and `@flung.dev/connect/core` has the calls with no element. |

## Properties

The React component takes these. The element takes the same as attributes (`base-url`, `platforms`, `mode`, `theme`) and properties (`token`, `labels`).

| Prop | Type | Required | Description |
|---|---|---|---|
| `token` | `TokenSource \| null` | yes | A connect token from your server, or a function that fetches a fresh one. |
| `baseUrl` | `string \| undefined` | no | Where the API lives; production when left out. |
| `platforms` | `readonly Platform[] \| undefined` | no | Offer only these platforms. |
| `mode` | `'popup' \| 'redirect' \| undefined` | no | `redirect` sends the whole page to the platform and back, for pages that cannot open windows. |
| `theme` | `'light' \| 'dark' \| undefined` | no | `light` or `dark`. Follows the page's colour scheme when left out. |
| `labels` | `Partial<ConnectLabels> \| undefined` | no | Any of the panel's words, to put it in another language. |
| `className` | `string \| undefined` | no | A class for the element itself. |
| `style` | `CSSProperties \| undefined` | no | Styles for the element, such as its `--flung-*` custom properties. |
| `onLoad` | `((detail: LoadDetail) => void) \| undefined` | no | The accounts were read: on first show and after every change. |
| `onConnect` | `((detail: ConnectDetail) => void) \| undefined` | no | A connect or reconnect finished. |
| `onDisconnect` | `((detail: DisconnectDetail) => void) \| undefined` | no | An account was disconnected. |
| `onError` | `((detail: ErrorDetail) => void) \| undefined` | no | A call or a connect failed. |

## Events

The element sends these, bubbling and crossing its shadow root. The React component takes them as callbacks.

### `flung-load`

`flung-load`: the accounts were read, on first show and after every change.

| Field | Type | Required | Description |
|---|---|---|---|
| `accounts` | `Account[]` | yes | The connected accounts the panel shows, newest first. |

### `flung-connect`

`flung-connect`: a connect or reconnect finished. `accounts` are the ones stored; Facebook stores one per page.

| Field | Type | Required | Description |
|---|---|---|---|
| `session` | `ConnectSession \| null` | yes | The connect session, or null when the person came back from a redirect. |
| `accounts` | `Account[]` | yes | The accounts stored. |

### `flung-disconnect`

`flung-disconnect`: an account was disconnected.

| Field | Type | Required | Description |
|---|---|---|---|
| `account` | `Account` | yes | The account, now `disconnected`. |

### `flung-error`

`flung-error`: a call or a connect failed. `code` is the API's stable code, such as `forbidden` or `access_denied`.

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | `string` | yes | The API's stable code, or the platform's, such as `access_denied`. |
| `message` | `string` | yes | What went wrong, for a person. |

## Styling

Set any of these custom properties on the element, or style its parts with `::part()`.

| Custom property |
|---|
| `--flung-font` |
| `--flung-text` |
| `--flung-muted` |
| `--flung-surface` |
| `--flung-raised` |
| `--flung-border` |
| `--flung-accent` |
| `--flung-accent-text` |
| `--flung-danger` |
| `--flung-warning` |
| `--flung-radius` |

| Part |
|---|
| `::part(list)` |
| `::part(message)` |
| `::part(panel)` |
| `::part(badge)` |
| `::part(name)` |
| `::part(platform)` |
| `::part(account)` |
| `::part(status)` |
| `::part(form)` |
| `::part(note)` |
| `::part(confirm)` |

## Words

Every word the panel shows. Pass `labels` with any of these keys to change them; `{platform}`, `{account}`, `{message}` and `{date}` are filled in.

| Key | Default |
|---|---|
| `panel` | Connected accounts |
| `connect` | Connect |
| `connectAnother` | Add another |
| `reconnect` | Reconnect |
| `disconnect` | Disconnect |
| `confirmDisconnect` | Disconnect {account}? Posts to it will stop. |
| `keep` | Keep it |
| `cancel` | Cancel |
| `continue` | Continue |
| `handleBluesky` | Your Bluesky handle, such as alice.bsky.social (optional) |
| `handleMastodon` | Your Mastodon server, such as mastodon.social |
| `waiting` | Finish signing in to {platform} in the window that opened. |
| `blocked` | Your browser did not open the {platform} window. |
| `openSignIn` | Open {platform} sign-in |
| `connected` | {platform} is connected. |
| `failed` | {platform} was not connected: {message} |
| `expired` | Signing in to {platform} took too long. Try again. |
| `disconnected` | {account} is disconnected. |
| `needsReconnect` | Needs reconnecting |
| `reconnectBy` | Reconnect by {date} |
| `loading` | Loading accounts… |
| `loadFailed` | Could not load accounts: {message} |
| `empty` | There is nothing to connect here. |
| `noToken` | This panel has no connect token yet. |

## Without the element

`@flung.dev/connect/core` has `ConnectClient`, for a page that draws its own panel.

| Method | What it does |
|---|---|
| `platforms()` | Every platform, and whether this Flung can connect it. |
| `accounts()` | The connected accounts the token may see: its profile's, or the whole workspace's. |
| `connect(platform: Platform, options: { handle?: string \| undefined; redirectUrl?: string \| undefined } = {})` | Starts connecting a new account. `handle` is the Bluesky handle, or the Mastodon instance (required there). |
| `reconnect(accountId: string, options: { redirectUrl?: string \| undefined } = {})` | Starts reconnecting an account that needs it; the person must sign in as the same platform user. |
| `disconnect(accountId: string)` | Deletes the account's stored tokens. It stays listed as `disconnected`. |
| `session(id: string)` | A connect session's state: pending, connected, failed or expired. |
| `waitForSession(id: string, options: { signal?: AbortSignal \| undefined; intervalMs?: number \| undefined } = {})` | Resolves once the session is no longer `pending`. Rejects with an `AbortError` when `signal` aborts. |

## See also

| Doc | Why |
|---|---|
| [Add account connecting to your site](https://docs.flung.dev/connect-accounts.md) | The whole flow, server and page |
| [Create a connect token](https://docs.flung.dev/reference/api/post-v1-connect-tokens.md) | The endpoint your server calls |
| [TypeScript SDK](https://docs.flung.dev/reference/sdk.md) | Making the token from your server |