React components
Props, callbacks and views of the AdQuestWidget and QuestWidget components.
On this page
AdQuestWidget
The lottery-first widget with token balance, entries, claims and the earn-token journey. Import it from @adquest/sdk/react and import @adquest/sdk/styles.css once.
| Prop | Type | Meaning |
|---|---|---|
| apiKey | string (required) | Your public API key. |
| baseUrl | string (required) | The API URL, including /api/v1. |
| externalUserId | string (required) | Your ID for the user. |
| participantToken | string | The participant token from your backend. |
| previewToken | string | A Theme Studio preview token. |
| theme | AdQuestTheme | Typed theme overrides, such as layoutPreset, colors and copy. |
| locale | string | Widget language, en or fa. |
| initialView | WidgetView | The first view to show. |
| autoLoad | boolean | Load data on mount. Defaults to true. |
| title, description | string | Header text. |
| className | string | A class for the root element. |
| displayName | string | The participant’s name. |
| requireProfile, onSubmitProfile | boolean, function | Ask for a name and avatar first, and receive them. |
Callbacks
| Callback | Called with | Use it to |
|---|---|---|
| onReady | nothing | Hide your loading indicator. |
| onComplete | QuestCompleteResult | Show completion feedback and refresh your server-backed state. |
| onEntry | LotteryPurchase | Show entry confirmation. |
| onClaim | LotteryClaim | Show claim submission feedback. |
| onNavigate | { view, canGoBack, immersive? } | Keep host navigation in sync. |
| onAuthRequired | nothing | Refresh the participant token through your backend. |
| onError | { code, message } | Show a recoverable error or account action. |
| onClose | nothing | Close the drawer, screen or modal that contains the widget. |
| hostNavigation | boolean | Set true when your app provides the header. The widget hides its own header and shows a Back to platform button on the home page. |
| onExit | nothing | The user pressed Back to platform on the home page. Close or leave the screen that contains the widget. |
Views
WidgetView is one of lotteries, lottery-detail, earn-tokens, my-entries, results, claims, quests, history or profile.
A ref to AdQuestWidget exposes navigate(view), getView() and goBack(). goBack() returns false at the root, where your app can close the experience.
QuestWidget
A quest-only placement.
| Prop | Type | Meaning |
|---|---|---|
| apiKey, baseUrl, externalUserId, participantToken | string | As for AdQuestWidget. Optional when wrapped by AdQuestProvider. |
| theme | AdQuestTheme | Typed theme overrides. |
| showHeader | boolean | Show the title row. Defaults to true. |
| title, description, className, autoLoad | mixed | As for AdQuestWidget. |
| onComplete | (result: QuestCompleteResult) => void | Called when a quest completes. |
| onBack, onOpenRewards | () => void | Navigation hooks for the host. |
| onQuestFocusChange | (focused: boolean) => void | Called when a quest opens or closes. |
| resetToListToken | number | Change it to send the widget back to the quest list. |
| wrapWithProvider | boolean | Wrap with AdQuestProvider. Set false when you already provide one. |
Language and formatting
- locale (en or fa, region tags such as en-US accepted) sets the widget language. Anything else uses English. Changing the prop updates the widget at once. Quest and lottery content follows the language of the participant session, so create a new session when the language changes.
- The widget sets lang and dir on its root element. Persian renders right-to-left.
- Dates and numbers use Intl for the resolved language, with Persian digits and calendar for fa.
- Quest names and lottery text come from the server and are shown as sent. When the server falls back to another language, that text carries its own lang and dir.
- Theme copy for startQuest, buyTicket, questsTab and rewardsTab wins when you set a custom value. A missing value, or the original English default (START QUEST, BUY A TICKET, QUESTS, REWARDS, case-sensitive), follows the SDK language instead.
Theme overrides
The widget loads the platform’s published theme. Pass a typed theme to override values in code. A host override beats the published theme, so remove it if you want the dashboard to control that value. Keep @adquest/sdk/styles.css imported for the base layout.
import type { AdQuestTheme } from "@adquest/sdk";
const theme: AdQuestTheme = {
layoutPreset: "quests_rewards",
primaryColor: "#ff9a3e",
borderRadius: "12px",
colors: {
background: "#0c0c0c", surface: "#18181a",
text: "#f5f2ef", muted: "#a39b96",
},
currency: { tokenLabel: "Tokens", ticketLabel: "Tickets" },
copy: { questsTab: "Quests", rewardsTab: "Rewards" },
};
// Pass theme={theme} to AdQuestWidget or QuestWidget.Use the typed theme instead of overriding internal class names. Check text contrast, small screens, loading and error states, and long translations.
Default spacing
The default design spaces everything on a 4px base unit and an 8px grid. Every padding, margin and gap in @adquest/sdk/styles.css uses one of the steps below, so spacing stays consistent from screen to screen. The scale is fixed: it is not a theme value, and neither Theme Studio nor a typed theme can change it.
| Step | Size | Typical use |
|---|---|---|
| --adquest-space-1 | 4px | Gaps between an icon and its label, tight text stacks. |
| --adquest-space-2 | 8px | Gaps between small items, badge and chip padding. |
| --adquest-space-3 | 12px | Field and list-item padding. |
| --adquest-space-4 | 16px | Card padding, gaps between related blocks. |
| --adquest-space-5 | 20px | Side padding of a screen. |
| --adquest-space-6 | 24px | Sheet padding, gaps between sections. |
| --adquest-space-8, -10, -12, -16 | 32px, 40px, 48px, 64px | Large breaks, such as the top of a sheet. |
- Controls drawn smaller than 44px (the currency icon buttons, the header back button and the quantity stepper) keep their look and have an invisible 44px tap area.
- Values you set in a typed theme, such as card padding, button height and quest card content spacing, still apply. Only the defaults, used when you set nothing, sit on the scale.
- The variables are internal. Do not read or override --adquest-space-* in your own CSS, because they can change between versions.
- Persian (fa) renders right-to-left with the same spacing.
Components and hooks
For a custom interface, @adquest/sdk/react also exports AdQuestProvider, ClaimCountdown, ClaimsView, CurrencyBar, LotteryDetailView, LotteryList, LotteryResultsView, LotteryWinnerList, MyEntriesView, ParticipantGate, QuestModal, QuestList, QuestDetail, QuestPlayer, QuestStepper, QuestResultSheet, ResultPanel and RewardHistoryView, plus the hooks useAdQuest, useBalanceHistory, useLotteries, useLotteryClaims, useLotteryEntry, useParticipantSession, useQuestSession and useTokenBalance.