@reqdesk/sdk-react

React provider, views, hooks, and TanStack Query options for the Reqdesk SDK. This is the package that powers @reqdesk/widget's React entry and the Reqdesk browser extension's side panel — so anything you can build with the widget you can also build directly on this package, with your own chrome around it.

If you want the floating bubble, install @reqdesk/widget. If you want to drop ticket submission into your own layout — your own header, your own routing, your own state — install this.

Install

npm install @reqdesk/sdk-react @reqdesk/sdk-core @tanstack/react-query
# or
bun add @reqdesk/sdk-react @reqdesk/sdk-core @tanstack/react-query

Peer deps: react ^18 || ^19, react-dom ^18 || ^19, @tanstack/react-query ^5.

Quick start

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReqdeskProvider, SubmitTicketView, MyTicketsView } from '@reqdesk/sdk-react'

const queryClient = new QueryClient()

export function SupportPage() {
  return (
    <QueryClientProvider client={queryClient}>
      <ReqdeskProvider
        apiKey="rqd_pk_…"
        apiUrl="https://api.reqdesk.support"
        language="en"
      >
        <SubmitTicketView />
        <MyTicketsView />
      </ReqdeskProvider>
    </QueryClientProvider>
  )
}

ReqdeskProvider owns the API client, the auth state machine, theme tokens, i18n, and the host adapter — every other export reads from this context.

Provider

import { ReqdeskProvider, useReqdeskContext } from '@reqdesk/sdk-react'
import type { ReqdeskProviderProps, ReqdeskContextValue } from '@reqdesk/sdk-react'

Props worth knowing:

| Prop | Type | Notes | |------|------|-------| | apiKey | string | Project-scoped (rqd_pk_…) or workspace-scoped (rqd_ws_…) | | apiUrl | string | Defaults to window.location.origin — set when embedding cross-origin | | language | 'en' \| 'ar' | Drives copy + dir | | theme | ThemeConfig | primaryColor, mode, borderRadius, logo, brandName | | customer | CustomerConfig | Pre-fill email, name, userHash, userHashTimestamp, refreshIdentity | | auth | OidcAuthConfig | Optional Keycloak — when set, the SDK exposes a sign-in flow via oidc-spa | | actions | ReactMenuActionInput[] | Custom menu entries (imperative onClick or declarative trigger) | | display | { mode, side, width, height } | Controls sheet vs popover surfaces | | initialPreferences | Partial<WidgetPreferences> | Defaults + reset target | | userPreferences | WidgetPreferences \| null | Host-stored prefs that override defaults | | onPreferencesChange | (next) => void | Round-trip preferences through your API | | hostAdapter | HostAdapter | Override the runtime seam (used by the extension to inject chrome.*) |

Views

Drop these into any layout:

import {
  SubmitTicketView,   // title, description, priority, attachments, tags
  MyTicketsView,      // history list with status + reply count
  TicketDetailView,   // full thread + reply composer
  TrackTicketView,    // anonymous lookup by tracking token
} from '@reqdesk/sdk-react'

Every view is a self-contained, accessible component. They share the provider's auth state, so a logged-in (signed or SSO) user sees their own tickets without ever typing an email.

Hook + query options

import {
  useReqdesk,
  reqdeskTicketDetailOptions,
  reqdeskMyTicketsOptions,
  reqdeskUserOptions,
  reqdeskTrackTicketOptions,
  reqdeskCategoriesOptions,
} from '@reqdesk/sdk-react'

function MyHeader() {
  const { isOpen, open, close, preferences, setPreferences } = useReqdesk()
  // …
}

// Build your own list against the same query key:
const { data } = useQuery(reqdeskMyTicketsOptions({ apiClient, email }))

The query options are factories returning canonical queryOptions(...) shapes — composable with TanStack Query's useQuery, useSuspenseQuery, prefetchQuery, and the persister plugins. Reuse the same keys to share cache with the widget.

Host adapter

The host adapter is the seam between the React surface and the platform that surrounds it. The web defaults to noopHostAdapter; the extension injects chrome.*-backed handlers for screenshots, screen recording, page-metadata harvest, and connection picking.

import { HostAdapterProvider, type HostAdapter } from '@reqdesk/sdk-react'

const adapter: HostAdapter = {
  capturePageMetadata: async () => ({ url, title, viewport, … }),
  captureScreenshot: async (scope) => ({ dataUrl, scope, capturedAt }),
  recordScreen: async (opts) => ({ start, stop, … }),
  resolveProject: async () => ({ projectId, source: 'auto-detect' }),
  // …
}

<HostAdapterProvider adapter={adapter}>
  <ReqdeskProvider …><SubmitTicketView /></ReqdeskProvider>
</HostAdapterProvider>

Build your own when your host has capabilities the web doesn't — Tauri windows, Electron desktopCapturer, native shells.

Ledger primitives

The SDK exports the Reqdesk Ledger design-system primitives so the surfaces you build against this package look and feel exactly like the rest of Reqdesk:

import { LedgerEyebrow, LedgerDivider, LedgerInput, LedgerIconButton } from '@reqdesk/sdk-react'

Each primitive ships with sensible light + prefers-color-scheme: dark fallbacks, so they look right even if you skip the provider.

Versioning

@reqdesk/sdk-react is published in lockstep with @reqdesk/widget — the widget's React entry just re-exports from here, plus the FAB and shadow DOM. Bump together; never run a widget against a mismatched core.

License

See LICENSE in the monorepo root.