Overview
Connect panel
@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. |
| 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 | The whole flow, server and page |
| Create a connect token | The endpoint your server calls |
| TypeScript SDK | Making the token from your server |