Guard components

Guards conditionally render children based on connection state, provider selection, and error conditions. Import from @arlopass/react/guards.

import {
  ArlopassConnectionGate,
  ArlopassProviderGate,
  ArlopassChatReadyGate,
  ArlopassNotInstalled,
  ArlopassDisconnected,
  ArlopassConnected,
  ArlopassProviderNotReady,
  ArlopassHasError,
  ArlopassChatNotReady,
  ArlopassChatReady,
  ArlopassErrorBoundary,
} from "@arlopass/react/guards";

Positive gates

Gates render their children when a condition is met and show a fallback otherwise.

ArlopassConnectionGate

Renders children when the client is connected. Shows fallbacks for loading, error, and not-installed states.

Prop	Type	Default	Description
`fallback`	`ReactNode`	`null`	Rendered while connecting or when disconnected.
`errorFallback`	`(props: { error: ArlopassSDKError; retry: (() => Promise<void>) \| null }) => ReactNode`	—	Rendered when connection fails. Receives the error and a retry function.
`notInstalledFallback`	`ReactNode`	—	Rendered when the Arlopass extension is not installed.
`children` required	`ReactNode`	—	Rendered when connected (state is "connected" or "degraded").

<ArlopassConnectionGate
  fallback={<p>Connecting…</p>}
  notInstalledFallback={<p>Please install the Arlopass extension.</p>}
  errorFallback={({ error, retry }) => (
    <div>
      <p>Error: {error.message}</p>
      {retry && <button onClick={retry}>Retry</button>}
    </div>
  )}
>
  <MyApp />
</ArlopassConnectionGate>

ArlopassProviderGate

Renders children when a provider/model pair is selected.

Prop	Type	Default	Description
`fallback`	`ReactNode`	`null`	Rendered when no provider is selected.
`loadingFallback`	`ReactNode`	—	Rendered while providers are being listed. Falls back to fallback if not set.
`children` required	`ReactNode`	—	Rendered when a provider is selected.

<ArlopassProviderGate fallback={<ProviderPicker />}>
  <Chat />
</ArlopassProviderGate>

ArlopassChatReadyGate

All-in-one gate that checks connection, provider selection, and error state. Renders children only when everything is ready to chat.

Prop	Type	Default	Description
`connectingFallback`	`ReactNode`	`null`	Rendered while connecting.
`notInstalledFallback`	`ReactNode`	—	Rendered when the extension is not installed.
`providerFallback`	`ReactNode`	`null`	Rendered when connected but no provider is selected.
`errorFallback`	`(props: { error: ArlopassSDKError; retry: (() => Promise<void>) \| null }) => ReactNode`	—	Rendered on connection failure.
`children` required	`ReactNode`	—	Rendered when connected and a provider is selected.

<ArlopassChatReadyGate
  connectingFallback={<Spinner />}
  providerFallback={<ProviderPicker />}
>
  <Chat />
</ArlopassChatReadyGate>

Negative guards

Negative guards render children when a condition is not met. They accept ReactNode or a render function as children.

Prop	Type	Default	Description
`ArlopassNotInstalled`	`Component`	—	Renders children only when the Arlopass extension is not detected. Children type: ReactNode \| (() => ReactNode)
`ArlopassDisconnected`	`Component`	—	Renders children when the client is not connected (any state except "connected" or "degraded"). Children type: ReactNode \| (() => ReactNode)
`ArlopassConnected`	`Component`	—	Renders children only when connected ("connected" or "degraded"). Children type: ReactNode \| (() => ReactNode)
`ArlopassProviderNotReady`	`Component`	—	Renders children when no provider is selected. Children type: ReactNode \| (() => ReactNode)
`ArlopassHasError`	`Component`	—	Renders children when a connection error is present. Children receive { error, retry } as a render prop. Children type: (props: { error: ArlopassSDKError; retry: (() => Promise<void>) \| null }) => ReactNode
`ArlopassChatNotReady`	`Component`	—	Renders children when chat is not ready (not connected or no provider selected). Children type: ReactNode \| (() => ReactNode)
`ArlopassChatReady`	`Component`	—	Renders children only when chat is ready (connected and provider selected). Children type: ReactNode \| (() => ReactNode)

<ArlopassNotInstalled>
  <p>Install the Arlopass extension to use AI features.</p>
</ArlopassNotInstalled>

<ArlopassHasError>
  {({ error, retry }) => (
    <div>
      <p>{error.message}</p>
      {retry && <button onClick={retry}>Retry</button>}
    </div>
  )}
</ArlopassHasError>

ArlopassErrorBoundary

A React error boundary that catches rendering errors in the child tree. Standard class-component boundary with a render-prop fallback.

Prop	Type	Default	Description
`fallback` required	`(props: { error: Error; resetErrorBoundary: () => void }) => ReactNode`	—	Render prop called when an error is caught. Receives the error and a reset function.
`onError`	`(error: Error, errorInfo: ErrorInfo) => void`	—	Optional callback for logging or telemetry.
`children` required	`ReactNode`	—	Child tree to wrap with the error boundary.

<ArlopassErrorBoundary
  fallback={({ error, resetErrorBoundary }) => (
    <div>
      <p>Something went wrong: {error.message}</p>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  )}
  onError={(err, info) => console.error(err, info)}
>
  <Chat />
</ArlopassErrorBoundary>