Blocks
Composed patterns for balances, markets, trade review, swapping, picking assets, and documentation.
Includes ReceiveBlock, ClaimRewardBlock, LoginBlock, DepositBlock, SwapBlock, FromPickerBlock, ToPickerBlock, AccountBlock, TokenActionBlock, ConfirmBlock, LanguageBlock, ManagePositionBlock, TradeHistoryListBlock, TradeHistoryDetailBlock, TargetBlock, PresetPickerBlock, PositionBlock, AssetsBlock, ProfileBlock, RewardBlock, SoundHapticsBlock, SignalsBlock, and NotificationsBlock, and the ScreenHeader they all share.
MarketRow, TradeEntry, InstallCommand and MarketingHero are still imported from the blocks entry, but they are single components, not whole screens, so they are documented with their families: MarketRow in Financial data, TradeEntry in Fields & inputs, and InstallCommand and MarketingHero in Actions & surfaces.
Issue #26. Entry: blocks. Import each block from its own entry: @bloxwap/hig/react/blocks/<name> on web, for example @bloxwap/hig/react/blocks/install-command, blocks/market-row and blocks/marketing-hero, and @bloxwap/hig/native/<name> on native, for example @bloxwap/hig/native/swap-block, native/market-row and native/reward-block. The aggregate entries, @bloxwap/hig/react/blocks and @bloxwap/hig/native/blocks, still export every block, but Metro does not remove unused exports, so one import from the native aggregate ships all of them: @bloxwap/hig/native/swap-block reaches 44 HIG files and @bloxwap/hig/native/blocks reaches 85. The native swap pieces have their own entries too: SwapKeypad and SwapCapsule in @bloxwap/hig/native/swap-parts, and SwapAmountCard and SwapPill in @bloxwap/hig/native/swap-amount-card. These need no Radix peer; smoke:packed-boundaries renders and bundles them with no Radix installed (#63). blocks/swap-block needs none either. blocks/trade-entry and the aggregate blocks entry need @radix-ui/react-dialog for the confirm step. LoginBlock’s info button uses the @radix-ui/react-popover peer, which is also imported by the aggregate web entry. blocks/swap-sheet (not in the aggregate) needs vaul. Import @bloxwap/hig/react/css once on web; tokens CSS is a separate explicit import.
Blocks were called recipes through 0.5.x. The recipes import paths are removed: import from @bloxwap/hig/react/blocks, @bloxwap/hig/react/blocks/<name> and @bloxwap/hig/native/blocks. node codemods/superseded.mjs --write <files> rewrites a host's imports.
API and anatomy
All data and actions are supplied by the host application.
| Block | Key props and behavior |
|---|---|
SwapBlock | Send, swap and bridge in one panel. tokens (and optional fromTokens, chains, hotTokenIds), the pair as from / to with onFromChange / onToChange or uncontrolled with defaultFrom / defaultTo, onAmountChange (From amount in token units), the host quote as received, fee, fees and quoteLoading, slippage / onSlippageChange, wallet, receive, and onSubmit(action). Details below. |
AccountBlock | An account at a glance: a header, the total with a deposit action, the pinned dollar balance, then every other holding by value. Details below. |
TokenActionBlock | One token and what can be done with it: where it is held, the chains it sits on, and the actions as equal full-width buttons. Details below. |
ConfirmBlock | The last look before a send: the amount as the headline, the destination address in full and the network as plain lines, a warning that the send cannot be taken back, then Cancel and Confirm side by side. Details below. |
TradeHistoryListBlock | A history of closed trades: a header, then one row per trade with the asset, its side and leverage, and the net result over its age. Details below. |
TradeHistoryDetailBlock | The full record of one closed trade: the asset, the net result as the headline figure, the trade's figures as rows, and the host's actions. Details below. |
LanguageBlock | Choose the app's language: a header, a search field, and each language as a row with its flag and a check on the one in use. Details below. |
PositionsBlock | Open positions filtered by All, Wins or Losses. Each row shows direction, leverage, size and stacked P&L. Close All always counts the full list and delegates confirmation to the host. |
ManagePositionBlock | One open position: margin against notional as a BarMark, the liquidation, mark and entry prices as a BarPnl, the host's actions as rows, and the position underneath. Details below. |
TargetBlock | A take profit or a stop loss on one position: the target as the headline figure, an info button for how the order fills, the entry and trigger prices on one bar, the unit, quick choices and the confirming action. Details below. |
PresetPickerBlock | Choose one value from quick choices, such as an order size or leverage: an optional header, the value as the headline figure, an optional row that opens the host's own entry, the choices as chips, then Cancel and the confirming action. Details below. |
PositionBlock | The position being opened or edited: a summary of what it costs and where it ends, an optional paper trading switch, and its settings as grouped rows. Details below. |
AssetsBlock | Choose a market: a search field, category capsules, All / Positions / Trend views, then the markets in sections by category, each with its signal disc. Details below. |
ProfileBlock | A person's profile as one screen: the avatar with a status dot, the name, then grouped rows for accounts, history, rewards and settings. Details below. |
RewardBlock | A competition: a prize pool or sweepstakes promotion, a choice of standings, the viewer's own standing, and the ranked list. Details below. |
SoundHapticsBlock | Sound, microphone, haptics and flash settings: one card per channel with a switch, and for a channel that is on its device, input meter and volume steps. Details below. |
SignalsBlock | The signals the viewer receives, in groups with a heading, a small help pill and switches. Details below. |
NotificationsBlock | The notifications the viewer receives: one card per kind with a switch, and a failure under its card. Details below. |
FromPickerBlock | Where assets come from: a connected wallet row (disconnect optional) or Connect wallet with a Generate address switch, above a searchable token list. Details below. |
ToPickerBlock | Where assets go: a destination address field with a scan button, on its own or above a searchable token list with or without the chain filter. Details below. |
Presentation mode uses a grid with logical numeric alignment and no block padding. The host can set matching column widths on each row through style/className, its compact height and the surrounding keyboard/option semantics. The number face inherits from that row. Slots render host content; keep decorative icons/indicators hidden from assistive technology, or give interactive controls their own names and deliberate keyboard behavior. Presentation rows accept no onSelect and emit no action feedback. Tiny prices keep the requested precision; unknown values remain —. Volume formatting and units stay host-owned. The optional identity slot belongs to presentation mode; action mode keeps its named HIG button. Hosts that use toFixed rounding should pass their already-rounded percent-point value plus explicit changeOptions to preserve binary rounding, trailing digits, signs and negative zero. Options use the same contract as Percent: the input is percent points, and the rendered style remains percent.
LoginBlock
Present LoginBlock in a gesture sheet to offer X, Apple, and Google sign-in. The host supplies the last-used provider, handles onLogin and onClose, and controls optional product analytics through analyticsEnabled and onAnalyticsChange. Start consent off for a new user. The info button beside Product analytics explains the optional data sharing in a web popover or native dialog. Pass disabled while authentication is starting, or pending with the providers whose sign-in is in flight to disable those rows alone. Omit onAnalyticsChange to leave the analytics row out, and pass analyticsDisabled to draw its switch unavailable while consent loads. The footer links to Bloxwap’s Terms of Use and Privacy Policy. Hosts can override the links and localize the labels, and pass onOpenLink to open them their own way, such as an in-app browser. On native, testID prefixes the block’s test IDs, titleRef reaches the heading so a sheet can move focus to it, and headingHint is read after the heading. On web, pass onMoreLogin to enable Email and Wallet under More options. Set lastUsed to the provider used most recently to highlight its button and pin the badge to the trailing edge. The disclosure starts expanded when Email or Wallet was last used.
ClaimRewardBlock
Show the prize amount, currency, full destination wallet address and chain with Claim and Cancel. Pass labeled rows in details for the drawing name, prize placement, or other award details. Use onClaim to open a separate ConfirmBlock showing the current wallet, and onCancel to dismiss the prize. The host submits the payout on confirmation and announces the receipt after the wallet is credited.
The block can also be the whole claim page, so the host needs no screen of its own. Every part of the claim step is optional, and a host that passes none of them gets the block above unchanged.
detailsrows come first, then the wallet and the chain. Values are plain text: for a countdown such as Time left, pass a new string as it changes.noteis one line of plain text under the details, such as where the prize is paid.attestation(label,checked,onCheckedChange, and optionallinks) draws a HIGCheckboxthe winner must tick. Claim is unavailable untilcheckedis true.links, such as the official rules, are drawn under the statement, not inside it, so a press on a link never ticks the box. Passlabels.attestationRequiredto say why Claim is unavailable: it is not drawn, and is the button's description on web and its accessibility hint on native.statusisready(the default),claiming,paid,expiredorwithheld. The host sets it:onClaimnow means "claim the prize", and the host sends the payout. Whileclaiming, Claim shows the busy spinner and neither it nor the checkbox can be used; Cancel and Back stay available, since leaving the page does not stop the payout.paid,expiredandwithheldare final: the checkbox and the actions give way to the status line, andpaidalso shows thetransactionlink. Passlabels.doneto show one button that callsonCancelin a final status; without it, the page is left through Back or the surface around it.- The status line's words are
labels.claiming,labels.paid,labels.expiredandlabels.withheld. HIG ships no text for them. The line sits in a live region (role="status"on web, a polite live region on Android, an announcement on iOS) that is there from the first render whenstatusis passed, so passstatus="ready"up front and each change is announced. errordraws an errorAlertabove the actions. Claim stays available, so the winner can try again. A final status draws no error.transactionand each ofattestation.linkstakelabel,hrefand an optionalonSelect. On web the link opens in a new tab; on native it opens throughLinking.openURL.onSelectreplaces that navigation on both, for a router or an in-app browser.onBack,backProps,headerAction,headingIdandstickyHeadermake the block a pane with the sharedScreenHeader, as onConfirmBlock. On native,stickyHeadermakes the block its own scroll view (stickyHeaderBackground,scrollComponent), andtestID(defaultclaim-reward) prefixes the test IDs of the header, note, attestation, links, status line and buttons.
ReceiveBlock
Offer both networks with mode="both" (the default), or pass mode="ethereum" or mode="solana" with just that network’s address. The combined mode initially shows Ethereum, the first of the two segments, with Solana after it. Use the segmented control beneath the QR code to switch the displayed address and copy action to Solana. Single-network modes show the network heading. The host supplies the addresses and can pass onCopy(network, address) to copy the selected address using its clipboard adapter.
DepositBlock
A deposit method picker with a centered header, an optional description, and a grouped list of available methods. Include the method ID qr to pin QR code first in the list. Selecting it calls onSelect with that method. Use headerAction for the close button. Other methods keep their supplied order. Each row shows its icon, label, description, and disclosure chevron. The method IDs apple-pay, cash-app, exchange, crypto, bank, and blink use the corresponding funding icons from the Bloxwap app. A host can supply icon for custom artwork. Selecting a row calls onSelect(method) so the host can open a wallet address, exchange transfer, or payment provider. Use onBack and headerAction for sheet navigation.
SwapBlock
SwapBlock was called SwapPanelBlock through 0.8.x and SwapPanel through 0.5.x. Those names, their props types and the blocks/swap-panel-block, blocks/swap-panel and recipes/swap-panel paths are removed; node codemods/superseded.mjs moves a host to SwapBlock and blocks/swap-block. The swap pieces around it keep their names: SwapSheet, SwapAmountCard, SwapPill, SwapKeypad, SwapToken and the other Swap… types.
SwapBlock is a From card and a To card joined by a flip control, with one action button that names itself from the pair: the same asset is Send, different assets on one chain is Swap, and different assets across chains is Bridge (swapAction(from, to) returns the same value). Until the pair and amount are valid the button is disabled and says what is missing: select a token, enter an amount, or insufficient balance.
<SwapBlock tokens={catalog} fromTokens={holdings} hotTokenIds={ranked}
from={from} to={to} onFromChange={setFrom} onToChange={setTo}
onAmountChange={setUnits} received={quote?.out} fee={quote?.feeUsd} fees={quote?.fees} quoteLoading={loading}
slippage={slippage} onSlippageChange={setSlippage}
wallet={{connected, address}} onConnect={connect} onDisconnect={disconnect}
submitting={executing} onSubmit={action => execute(action, quote)}/>One panel covers each flow with the same cards; the catalog page shows every one as an example state.
| Flow | From card | Bottom card | Props | Example |
|---|---|---|---|---|
| Swap | token | another token, same chain | the pair | swap |
| Bridge | token | a token on another chain | the pair | bridge |
| Send | token | recipient, still to be picked | destination with pending and onPress | send |
| Deposit to an account | account, dollars only | the account | caption on the token, lockFrom, destination, denominationSwitch={false} | deposit |
| Withdraw from an account | account | where it lands, with a limit note | as deposit, plus note | withdraw |
| Withdraw to another chain | account the user can change | pressable destination | destination with onPress | withdraw-chain |
| Stake | holding, token units | label and value rows | details, denomination='token' | stake |
| Unstake | position, token units | rows, with a warning | details, note, noteTone='negative' | unstake |
| Receive | QR code and address | hidden | receive, receiving | none |
Stake and unstake are one example each: the asset changes only the token data, not the layout.
- Tokens. A
SwapTokenis{id, symbol, name, chain, chainId}plus optionalicon,chainIcon,balance(token units),price(USD per unit) andkeywords(extra search text such as the contract address).balanceenables Max, Test and the balance check;priceenables the dollar and unit conversion and the estimate shown beforereceivedarrives. - Amount. The From amount is typed in dollars or token units; the capsule under it switches denomination and converts the entry. Keys typed while focus is in the panel, a paste, and the keypad all drive it.
onAmountChangealways reports token units as canonical decimal text, preserving up to 100 fractional places (18 for dollar-to-token conversion when token precision is omitted). Estimates use floating point; transaction callbacks do not. Setamountonly to resync the entry, for example to'0'after a submit.keypad='auto'shows the keypad for a coarse pointer on web and always on native;captureKeyboard(web) lets digits typed anywhere outside a text field drive the amount. - Pushed views. The token pickers and settings are views pushed inside the panel's own bounds, replacing the cards, each with a Back control; Escape pops one level on web and choosing a token pops to the cards.
view/onViewChange('main' | 'from' | 'to' | 'settings' | 'slippage' | 'fees') control the stack when the host needs to. - Pickers. Pressing a card pushes its picker: search, chain filter chips, an optional Hot section from
hotTokenIds, and the token list with arrow-key and Enter selection on web. The From picker shows the connected wallet with a disconnect control, or Connect wallet and the receive toggle; the To picker shows the recipient field whenonRecipientChangeis set, with a scan button whenonScanRecipientis set. On web ⌘F / Ctrl+F and ⌘K / Ctrl+K open the From and To pickers while the panel is mounted; passshortcuts={false}to leave the browser's own shortcuts alone. - Settings. The menu button pushes the settings view: the default denomination, slippage (presets plus a custom percent) and the fee breakdown one level deeper, then any host rows passed as
settings. - Receive view. With
receive={{address, qr, onCopy}}the From picker offers “Receive to an address”. The From card then shows the host's QR node beside the address in fixed-width rows with the leading and trailing characters emphasised, the To amount is hidden, and the action becomes “Send from your wallet” (callsonConnect). HIG ships no QR encoder or scanner: the host rendersqrand implementsonScanRecipient. - Fixed destination.
destination={{title, subtitle, icon, address, detail, onPress}}replaces the To token with a place the host already knows: a recipient wallet, a staking pool, a trading account. The To card becomes one compact row with no picker and no amount, the panel is one-way, the action is ready from the From side alone, andonSubmitreceives'send'.addressshows shortened with the wallet's colour disc;onPressmakes the card a button with a trailing chevron, for example to change the recipient;feeshows on the card when the host passes it. - Accounts. A token with a
caption(for example$22.72 available, or the same as a live figure,{value:22.72, options:{style:'currency', currency:'USD'}, suffix:' available'}) is presented as an account: the name over the caption beside one disc, with Max only. A small chevron follows the name while the side can still be changed. - Pending destination.
destination.pendingshows the destination as a placeholder; the action stays disabled and reads “Pick a destination” until the host supplies a real one. - Prices.
entryandexitdraw oneBarPnlwithout a card, scaled to the two prices: the stretch between them is filled in the result colour and the two prices read under it. This replaces an Entry row and an Exit row.priceOptionsformats them; the default is US dollars. Leave either out and there is no bar. - Details.
details=[{label, value, options, prefix, suffix}]are the other figures, such as size, notional, time held, fees and funding. They are drawn three to a line as a small label over its value, in the order given. A number is formatted withoptionsbetweenprefixandsuffixand updates place by place; a string is drawn as given, which suits a duration the host has already formatted. - Note.
noteis a line under the cards for a limit or a delay;noteTone='warning'or'negative'makes it a tinted capsule. - Heading and controls.
titleputs a heading above the cards andonBacka Back control beside it, for a panel that is its own screen or sheet. From 0.8.0 the heading is the sharedScreenHeaderon both platforms (the title centred, 17/24 weight 600, in a 44 unit row with Back on its leading edge), like every other block, so a push from another block to a titled panel keeps Back and the title in place; it was a left-aligned 24px (web) orHeading(native) title. Native test IDs stayswap-headerandswap-back, withswap-titleadded.headingIdsets the heading'sid(web) ornativeID(native).controls={false}leaves the action button alone at full width, andactionIconputs a decoration before its text. - Locked sides.
lockFrom/lockTokeep that side's token fixed: its card looks the same but does not open the picker, has no shortcut, and reset leaves the token in place. - Action label.
actionLabelnames the action once it is ready, in place of Send, Swap or Bridge: Stake, Deposit, Unstake. The host supplies the translated text. The prompts before it is ready (select a token, enter an amount, insufficient balance) do not change. - Host-held action.
actionDisabledholds the action for a reason only the host knows (below a minimum, no quote yet, a closed market), andactionStatusis what it then says. The panel's own prompts still come first.actionIntent='destructive'is for an action that cannot be undone, such as a burn. - Submission. While
submittingis true, operation-changing controls stop accepting edits. The host must still capture the exact amount, asset identities, destination, quote and expiry before awaiting execution, revalidate them in its transaction layer, and provide idempotency. An enabled button is not transaction authorization. Web global input belongs to one visible panel; setactive={false}for a retained inactive screen. - Amount limits. A token's
decimalsmust be an integer from 0 to 100. It caps keypad, pasted and externally supplied token amounts; dollars stop at two places.limitToBalancerejects edits above any known balance, including zero, and clamps external resync to that balance. Without the cap, insufficient amounts remain visible but cannot submit. Unknown balances are distinct from zero. - Artwork. A token's
iconandchainIconand a destination'sicontake an image URL or the host's own element, which fills the disc. - Host content.
bannersits above the From card (a pending transfer) andfooterunder the action (recent activity). - Starting amount. A mounted
amount(token units) seeds the entry in the default denomination. - Fixed denomination.
denominationSwitch={false}removes the conversion capsule under each amount and the denomination setting, and keeps both amounts indenomination(dollars by default). Use it when the host only has one of the two, for example dollars with no token price. - One way.
oneWayis for flows that only run top to bottom, such as a deposit: the control between the cards becomes a decorative down arrow instead of the flip button, and the pair cannot be exchanged. - Live numbers (required). Every number in the swap card that can change while the card is on screen updates through
NumberFlow: only the places that changed move, and the text is never swapped in one step. This covers the entered and received amounts, the conversion capsule, the From balance, the fee and slippage on the To card, an account caption, the destination detail, detail rows, the settings rows and fee breakdown, and the balances in the token pickers. The panel does this itself for everything it formats. For text the host writes, pass the figure as a number so the panel can do the same:details=[{label:'Staked', value:11.0735, suffix:' HYPE'}],caption={{value:234.68, options:{style:'currency', currency:'USD'}, suffix:' available'}},destination.detail={{value:3.1, suffix:'% APR'}}. A string is still accepted and is drawn as given; use it only for text that does not change, such as a tier name. A value that is loading or unknown shows…or—and does not roll in from zero. Reduced motion updates the same numbers without movement, and the accessible reading is always the final value. Host-drawn parts of the card follow the rule too:SwapNumber(web, from the swap panel entry) orNumberFlowfor aSwapAmountCardmetaorconversion, and for custom settings rows. On native the swap panel and pickers entries therefore need the optional Reanimated and Worklets peers of theanimated-numberentry. - Ownership. The panel never fetches a quote, reads a wallet or submits a transaction.
onSubmitis called once per accepted press and not whilesubmitting. - Submitting. While
submitting, the action shows its spinner, ignores presses and keeps its ready name (actionLabel, or Send, Swap or Bridge), or sayssubmittingLabel(host text such as “Burning…”) when given, even if the host has already cleared the amount (amount='0') or the balance has dropped: it never falls back to “Enter an amount” or “Insufficient …” mid-submit. WithoutsubmittingLabel, a held action (actionDisabled) still says itsactionStatus(such as “Signing…”). The keypad, typed keys, Max and Test leave the amount as it is untilsubmittingclears. A missing token or a pending destination still names itself first. Withoutsubmittingthe action text is unchanged.
SwapAmountCard, from the same web entry, is the From card on its own for a host that enters one amount without a pair, such as a position size. It draws the asset (name, symbol, icon as a URL or a host-drawn node, optional chainIcon and context line), capsule actions such as Max (use SwapPill), a meta line such as the balance, and the entered value with prefix, suffix, fractionDigits and trailingDot. conversion puts a capsule under the amount, and onSelect with selectLabel makes the slot choose the asset. The host owns the entry and the keypad; SwapKeypad is exported beside it.
<SwapAmountCard name="USD Coin" symbol="USDC" context="Hyperliquid" value={Number(entry)} prefix="$"
fractionDigits={typedDecimals} trailingDot={entry.endsWith(".")} amountLabel="Size"
actions={<SwapPill onClick={useMax}>Max</SwapPill>} meta="1,000 USDC" />Native has the same two from @bloxwap/hig/native/swap-amount-card (and from @bloxwap/hig/native/blocks): SwapAmountCard takes the same props (name, symbol, icon as a URL or element, chainIcon, context, actions, meta, value, amountLabel, prefix, suffix, fractionDigits, trailingDot, maximumFractionDigits default 8, conversion, onSelect, selectLabel, style) and draws the panel's From card: a string context or meta is drawn small and muted and a node as given, the actions stay their own targets on the trailing edge, and the amount is one element named by amountLabel whose value is the drawn text ($1.50, 12. while a dot is typed). testID (default swap-amount-card) prefixes -slot, -select, -name, -context, -actions, -meta, -amount and -conversion. SwapPill is the capsule (32dp, a 44dp target): children as text drawn small and muted, or nodes as given; onPress; disabled dims it and reads as unavailable; other Pressable props such as accessibilityLabel, testID or android_disableSound reach it.
<SwapAmountCard name="USD Coin" symbol="USDC" context="Hyperliquid" value={Number(entry)} prefix="$"
fractionDigits={typedDecimals} trailingDot={entry.endsWith('.')} amountLabel="Size"
actions={<SwapPill onPress={useMax}>Max</SwapPill>} meta="1,000 USDC"/>SwapSheet presents the panel in a gesture sheet: @bloxwap/hig/react/blocks/swap-sheet on web (the web GestureSheet) and @bloxwap/hig/native/swap-sheet on native (the native GestureSheet). It takes every SwapBlock prop plus open, onOpenChange, a required accessible title and, on web, an optional trigger. Views push inside that one sheet, which follows the height of the view on show. Escape and Back pop a pushed view first; from the cards, Escape, the scrim and a downward drag close the sheet, and a reopened sheet starts on the cards. The native SwapSheet needs the same peers and the same GestureSheetHost as GestureSheet, and no sheet library; on Android the hardware Back button pops a pushed view before it closes the sheet.
<SwapSheet title='Swap' open={open} onOpenChange={setOpen} trigger={<Button>Swap</Button>} tokens={catalog} onSubmit={execute}/>FromPickerBlock and ToPickerBlock
The two pickers are the swap panel's token views as standalone blocks, for a host that picks a source or a destination outside the panel: in its own sheet, a page, or a step of a flow. They carry no sheet or overlay of their own; place them in a Dialog, a GestureSheet or any container. SwapBlock uses the same two blocks for its pushed views.
Both share one token list: tokens (a wallet's holdings, a whitelist or a whole catalog), selected, onSelect, optional chains, hotTokenIds and loading. The search and address fields are the standard rounded HIG inputs. chainFilter={false} leaves out the chain filter, for a single chain or a list that should not be narrowed by chain; it is also left out when the tokens are all on one chain.
import {FromPickerBlock, ToPickerBlock} from '@bloxwap/hig/react/blocks/pickers';
// Destination address only
<ToPickerBlock address={address} onAddressChange={setAddress} addressPlaceholder={shortWallet} onScan={openScanner}/>
// Address, then the asset, filtered by chain
<ToPickerBlock address={address} onAddressChange={setAddress} onScan={openScanner} tokens={catalog} selected={to} onSelect={setTo}/>
// The same without the chain filter
<ToPickerBlock tokens={catalog} chainFilter={false} selected={to} onSelect={setTo}/>
// No wallet yet: connect, or generate an address to send to
<FromPickerBlock wallet={{connected: false}} onConnect={connect} generateAddress={generating} onGenerateAddressChange={setGenerating} tokens={catalog} onSelect={setFrom}/>
// Connected: holdings, with sign-out
<FromPickerBlock wallet={{connected: true, address}} onDisconnect={disconnect} tokens={holdings} selected={from} onSelect={setFrom}/>| Variant | Props |
|---|---|
ToPickerBlock, address only | address, onAddressChange, optional addressPlaceholder and onScan; no tokens |
ToPickerBlock, with chains | add tokens and onSelect |
ToPickerBlock, without chains | add chainFilter={false} |
FromPickerBlock, not connected | wallet={{connected:false}}, onConnect, and generateAddress / onGenerateAddressChange for the switch |
FromPickerBlock, connected | wallet={{connected:true, address}}; onDisconnect shows the sign-out button, omit it where signing out does not belong |
FromPickerBlock, whitelist | no wallet: the token list alone |
- Generate address is a switch, not an action: it reports the new value and the user goes on to pick a chain and an asset. The host then shows the address to send to, for example with
WalletAddress, orSwapBlock's receive view. - Scanning and connecting belong to the host: HIG ships no QR scanner and no wallet connection.
onScanandonConnectonly report the press. - Search matches the token's name, symbol, chain and
keywords, so put the contract address inkeywordsto make a pasted address find its token. - Keyboard on web: with focus in the search field, the arrow keys move through the list and Enter selects.
- No search.
search={false}leaves out the search field, for a list of two or three tokens such as a withdraw picker. On web no row is highlighted until the pointer moves over one, because there is no arrow-key cursor; each row is still a button in the tab order. - Balances. A row draws a balance only when it is above zero;
zeroBalancesalso draws a known zero, for a list of every asset the account can hold. A token'sunitsSuffixfollows its balance figure (1.005 HYPE), and itsdetailreplaces the chain on the second line, for a list whose tokens are not told apart by chain; the search still matches the chain. - Input attributes.
searchInputPropsand, onToPickerBlock,addressInputPropsreach the inputs: on web any<input>attribute, includingname,autoComplete,data-1p-ignore,data-lpignore,data-form-type, a monoclassNameandonFocus/onBlur; on native anyTextInputprop, includingonFocus/onBlur,textContentTypeandstyle. The value and its change handler stay the block's. A hostonKeyDownon the web search runs first; the list's arrow keys and Enter then run unless it calledpreventDefault().searchRefandaddressRefgive the host the input itself, for example to register it with a bottom sheet's keyboard handling or to focus it. - Visible labels.
searchLabelandaddressLabeldraw a visible label over the field (aFieldlabel, 8 units above it on native and the field gap on web), which then names the field in place of the built-in hidden name. Without them the fields are named by the built-in “Search tokens” and “Recipient”, as before. - Selected row and row attributes (0.8.0). The row of
selectedis markedaria-current="true"on web (native already read it asaccessibilityState.selected), besides its drawn “Selected”.tokenRowProps={token => props}gives each token's row host attributes: on webdata-*,id,titleandaria-describedby(typePickerRowProps; HIG keeps the row's type, class, state and handlers), on nativetestID(replacingswap-token-<id>),nativeIDandaccessibilityHint. - Inside a host sheet (native). The list is a bounded
FlatList.listComponentrenders the rows through the host's list instead, such as aFlatListwhoserenderScrollComponentisGestureSheetScrollView, so it scrolls inside the sheet and hands drags to it; the host's component receives HIG's boundedstyleand may override it.SwapHostContext, now exported from@bloxwap/hig/native/pickersand theblocksaggregate, does the same for every picker under it, asSwapSheetuses it;listComponenton the block wins.
AccountBlock
AccountBlock shows one account: a header with Back on the leading edge, the title in the centre and an optional action on the trailing edge; under it the total on the leading edge and the deposit action on the trailing edge; then the holdings as AssetBalanceRow capsules 8 units apart. It is available from @bloxwap/hig/react/blocks/account-block, @bloxwap/hig/native/account-block and the blocks aggregates.
<AccountBlock assets={holdings} onBack={goBack} onShowAddress={openAddress} onDeposit={openDeposit}
onAssetSelect={asset => open(asset.id)}/>- Account address.
onShowAddressputs a QR button on the trailing edge of the header, above the deposit action. The host shows the address when it is pressed, for example in aDialogorSheetwithWalletAddress; the card never holds the address.headerActionreplaces the QR button with a host control. - Assets. An
AccountAssetis{id, name, symbol}plus optionalicon(an image URL or a host element),balance(token units),price(USD per unit) andvalue(dollars). The value shown isvalue, orbalance × pricewhen both are known, or the unknown dash. - Pinned dollar balance. The asset whose symbol is
pinnedSymbol(defaultUSDC) is always the first row and is always shown: when the account does not hold it, the row reads $0.00. It shows its dollar value alone, because its units are the same figure. - Order. Every other asset follows by dollar value, largest first. Unknown values come last and ties sort by name. The host does not sort.
accountRows(assets, pinnedSymbol)returns the same order for a host-drawn list. - Total.
balanceis the total in dollars. Without it the card sums the asset values; any unknown or nonfinite constituent makes the total unknown.nullreads as unknown. - Deposit.
onDepositshows the primary action beside the total.depositLabelreplaces the built-in text, for example with Add funds. - Header.
titlereplaces the built-in “Account”.onBackshows Back;headerActionis the trailing control. The title stays centred with either, both or neither.stickyHeaderpins it (see pinned headers; native also takesstickyHeaderBackgroundandscrollComponent), andheadingIdnames its heading. - Rows.
onAssetSelectmakes each row a button that reports its asset. Without it the rows are plain.selectable: falseon an asset keeps that one row plain. - Units.
units: falseon an asset draws no units line, for a ledger whose units are the same figure as its value.unitsOptionsformats an asset's units (at most six fraction digits by default) andunitsSuffixfollows them (PAPER). An asset whose value is unknown but whosebalanceis known shows its units as the headline figure, with no second line, in place of the unknown dash.unknownValue: 'dash'on the asset keeps the unknown dash over the units instead, for a value that is still loading, such as a price not yet read. - Tags. An asset's
tagis short muted host text under its figures (AssetBalanceRow tag), such as Perp, Spot or Staked, so two rows of the same symbol read apart without changing the symbol line. - Order.
order: 'given'keeps the rows after the pinned one in the order passed, for a ledger with a fixed order; the default'value'sorts them as above. A section's ownorderoverrides the block's.accountRows(assets, pinnedSymbol, {order, pinnedId})andaccountSectionRowstake the same options. - Pin by id.
pinnedIdpins the asset with that id, for a dollar ledger whose symbol is not unique (two USDC rows); without a match thepinnedSymbolmatch applies as before. A section's ownpinnedIdoverrides the block's. A row pinned by symbol shows its value alone; a row pinned by id keeps its ownunitssetting. - Sections.
sections=[{id, title, total, assets}]replaces the flat list with titled groups in the order given, 24 units apart, each a region named by its title with its rows 8 apart under a heading line that carries the group'stotalon the trailing edge (the sum of its asset values when left out;nullreads as unknown). Within a group the pinned asset leads only when the group holds it (no $0.00 placeholder), then the rest by value. A group with no assets is not drawn. Withoutbalancethe block total is the sum of the totals of the groups that are drawn, so a group with no assets adds nothing even when it has atotal; when any drawn group's total isnull, the block total is unknown too.onAssetSelectthen also receives the group:onAssetSelect(asset, section).accountSectionRowsandaccountSectionTotalreturn the same order and total for a host-drawn list.
<AccountBlock onDeposit={openDeposit} onAssetSelect={(asset, section) => open(section?.id, asset.id)} sections={[
{id: 'exchange', title: t.exchange, assets: [{id: 'perp', name: t.perp, symbol: 'USDC', value: 500, units: false}]},
{id: 'wallet', title: t.wallet, assets: walletAssets},
]}/>- Live numbers. The total, every section total, every value and every units figure update through
NumberFlow, as in the swap card. - Ownership. The card never reads a wallet, fetches a price or moves funds.
TokenActionBlock
TokenActionBlock is the screen for one token: the same header as AccountBlock with the ticker as its title, two BarMark bars, then the actions. The bars are read-only, so they are drawn without a card (surface={false}) and sit directly on the screen, as in ManagePositionBlock. The first bar is titled with the token's name, shows the total holding in dollars on its trailing edge, and divides among assets, the places the token is held (Staked, Core, Paper). The second is the same bar titled Chains that shows how many chains hold a balance and divides among chains. It is available from @bloxwap/hig/react/blocks/token-action-block, @bloxwap/hig/native/token-action-block and the blocks aggregates.
<TokenActionBlock symbol="HYPE" name="Hyperliquid" onBack={goBack}
assets={[{label: 'Staked', value: 320}, {label: 'Core', value: 239}, {label: 'Paper', value: 200}]}
chains={[{label: 'Base', value: 120}, {label: 'Hyperliquid', value: 639}]}
actions={[{id: 'send', onSelect: send}, {id: 'receive', onSelect: receive},
{id: 'stake', onSelect: stake}, {id: 'unstake', onSelect: unstake}]}/>- Bars.
assetsandchainsareBarMarkelements:{label, value}plus optionaltone,color,detailandid. Use one unit for both, usually dollars.chainsTitlereplaces the built-in “Chains”. Adetailcan be a live figure ({value, options, prefix, suffix}), which moves place by place on both platforms, like the total. - Actions only. Both bars are optional: leave out
chainsto draw the assets bar alone,assetsto draw the chains bar alone, or both for a card of commands with no breakdown.nameis needed only withassets; the ticker stands in without it. - Note.
noteis a line above the actions, for example why some are missing on a view-only account;noteTone='warning'or'negative'makes it a tinted capsule, as inSwapBlock. The buttons sit 8 units below the note. - Total.
valueis the holding in dollars. Without it the card sums the asset values; any unknown or nonfinite constituent makes the total unknown.nullreads as unknown. It updates place by place. - Units headline. For a token with no dollar value,
units(token units) withvalueleft out ornulltakes the total's place on the assets bar, followed byunitsSuffix(BLOX) and formatted withunitsOptions(at most six fraction digits by default). It updates place by place, and an unknownunits(null) reads as the dash. With a dollarvaluethe total is shown as before. - Chain count. The chains bar appears when the token has multiple supported chains. Its count shows how many hold a balance above zero.
- Actions. Each action is
{id, onSelect}plus optionallabel,disabledandintent. The idssend,receive,stakeandunstaketake a built-in translated label; any other id needslabel. They render in the order given, full width, 8 units apart and 16 below the bars. Leave out the actions a token does not support. - Intent. Actions default to
secondary, because the card offers equal choices. Setintent: 'primary'on at most one, or'destructive'for something like a burn. - Header.
onBackshows Back andheaderActionis the trailing control, as inAccountBlock, with the samestickyHeaderandheadingId. - Ownership. The card never reads a wallet or starts a flow. Each action only reports the press; the host opens its send, receive, stake or unstake screen, for example a
SwapBlock.
ConfirmBlock
ConfirmBlock is the last look before a send, usually in a sheet after the amount and destination are chosen: the header, the amount with its ticker as the headline, the destination address and the network as plain lines, a warning, then Cancel and the confirming action side by side. It is available from @bloxwap/hig/react/blocks/confirm-block, @bloxwap/hig/native/confirm-block and the blocks aggregates.
<ConfirmBlock amount={2.5} symbol="HYPE" address={destination} network="HyperEVM"
busy={sending} onBack={goBack} onConfirm={send} onCancel={close}/>- Amount.
amountis in token units and is formatted withamountOptions(at most six fraction digits by default);symbolfollows it, smaller and muted.nullreads as unknown.amountLabelnames the figure for assistive technology (“Amount: 2.5”, then the ticker); without it the figure is read alone. - Destination. The details are information, not controls, so they are plain lines with no card or row container: a muted label on the leading edge and the value on the trailing edge.
addressis shown in full beside the built-in “To”, always as two rows of monospace split at the middle, left to right in every locale. The characters people compare are emphasised in the text colour, the first 4 (6 when the address starts with0x) and the last 4, and the rest is muted, as inVerticalAddress. Assistive technology reads the plain address. Never shorten it here.networkis the value of the Network line.detailsadds lines under it, such as a fee:{label, value}plusvalueLabelfor a value that is not text. Native reads each line as one (“To, 0x…”). Values wrap by default;oneLineDetailskeeps the Network line and each ofdetailson one line, the label whole and the value truncated with an ellipsis (still read in full), while the address keeps its two rows. A value that is not text truncates the same way when it is inline text content (aspanon web, aTexton native, where it is set inside the line's one-line text). - Warning. The warning is on by default: the built-in heading “Double-check the address.” and a sentence that names the token and the network.
warningTitleandwarningreplace them with host text;warning={null}draws none. It is a note, not an alert: it is there before the user acts, so nothing is announced on its own. Something that does need announcing, such as a fee that cannot be read or a send that failed, goes innotice: the host's node (usually an errorAlert, which announces itself) drawn as given between the warning and the actions. Nothing by default. - Actions.
onConfirmreports the press on the confirming action, which is the primary button;confirmLabelreplaces the built-in “Confirm Send”.onCancelshows Cancel on its leading side (cancelLabel), the two sharing the row equally as inTargetBlock; without it the confirming action takes the full width.confirmDisableddraws the confirming action unavailable, andcancelDisableddraws Cancel unavailable withoutbusy(0.8.0). The two actions need not be Cancel and Confirm: a refusal that offers two ways forward, such as “Export account” beside “Withdraw first” with “Delete anyway” as the tertiary action, passes them ascancelLabel/onCancelandconfirmLabel/onConfirm. - Busy. While
busy, the confirming action shows a spinner and ignores presses, and Back and Cancel are unavailable, so a send that is being signed cannot be left half way.cancelWhileBusykeeps Back, Cancel and the tertiary action available during the wait, for one the host can abandon, such as a wallet signature for turning on an experiment.backWhileBusykeeps only Back available, for an action that finishes whether or not the user stays, such as closing a position: the user may leave the pane, but Cancel and the tertiary action stay held, since they cannot stop it. - Header.
titlereplaces the built-in “Confirm Send”.onBackshows Back andheaderActionis the trailing control, with the samestickyHeaderandheadingIdas the other blocks.backPropspasses attributes to Back asScreenHeadertakes them: web<button>attributes such as adata-testid, native Pressable props such as{android_disableSound: true}(0.8.0). - Test IDs per action (0.8.0).
confirmTestID,cancelTestIDandtertiaryAction.testIDset each action'sdata-testidon web; on native they replace<testID>-confirm,<testID>-canceland<testID>-tertiaryone by one, so a host keeps its own IDs (delete-account-withdraw,delete-account-export,delete-account-anyway) under one prefix. - Confirmations that are not sends. Every send part is optional, so the block also draws the last look before signing out, deleting an account, closing positions or turning on an experiment. Leave out
amountfor no headline (an amount withoutsymboldraws the figure alone), andaddressandnetworkfor no lines; withoutaddressthere is no built-in warning (passwarningfor one).childrenis what is being confirmed, drawn as given under the header and any send parts, in a column 12 apart: usually a mutedText, anAlertor aListGroupof figures.pointsadds a bulleted list in the muted colour under it, such as what deleting an account loses.confirmIntent='destructive'fills the confirming action with the negative role, for an action that deletes or ends something;confirmIntent='warning'fills it with the warning role (theButtonwarningintent, warning-coloured label on a translucent tint), for an action that goes ahead despite a caution, such as sending past awarning.tertiaryAction={{label, onSelect, tone, disabled}}adds a full-width ghost button 8 under Cancel and Confirm, such as “Delete anyway”;tone='destructive'draws its label in the negative colour, and it is unavailable whilebusy.
<ConfirmBlock title="Delete account?" confirmLabel="Delete" confirmIntent="destructive"
points={[keysErased, profileRemoved]} onCancel={close} onConfirm={remove}>
<Text tone="muted">This cannot be undone.</Text>
</ConfirmBlock>- Native test IDs.
testID(defaultconfirm) prefixes-header,-back,-title,-amount,-symbol,-to,-network,-detail-<index>,-body,-point-<index>,-warning,-confirm,-canceland-tertiary. - Ownership. The block never validates an address, reads a wallet or sends. The host checks the address before showing the block, and signs and sends on
onConfirm.
LanguageBlock
LanguageBlock is the screen for choosing the app's language: the same header as AccountBlock, a search field, then each language as a row. It is available from @bloxwap/hig/react/blocks/language-block, @bloxwap/hig/native/language-block and the blocks aggregates.
<LanguageBlock value={locale} onSelect={language => setLocale(language.code)} onBack={goBack}
languages={[
{code: 'en', name: 'English', description: 'English', flag: '/flags/us.svg'},
{code: 'fr', name: 'Français', description: 'French', flag: '/flags/fr.svg'},
]}/>-
Languages. A
LanguageOptionis{code, name}plus optionaldescriptionandflag.nameis the language in its own words anddescriptionis the reader's name for it, shown muted underneath.flagis round artwork: an image URL or a host element; without it the row shows the first two letters of the code. Rows keep the host's order. -
Selection.
valueis thecodein use; its row shows a check on the trailing edge.onSelectreports the language pressed. The host applies it and navigates. -
Search. The field at the top filters by name, description and code, ignoring case and accents, so
francaisfinds Français. No match shows the built-in “No results”. On web the arrow keys move through the matches from the field and Enter chooses the highlighted one, or the only one.search={false}leaves the field out for a short list.filterLanguages(languages, query)returns the same matches. -
Header.
titledefaults to the built-in “Language”.onBackshows Back andheaderActionis the trailing control, as inAccountBlock, with the samestickyHeaderandheadingId.descriptionis a muted line under the header. -
Disabled.
disableddims the rows, marks them unavailable and ignores presses (and Enter from the search field on web), for example while a change is being applied. -
Accessibility. The rows are a radio group named by the title; each row is a radio that reads the language's name and description, and carries its
codeas the language of its name. -
Large language lists. React windows lists above 50 languages inside the existing scroller. On native, place a standalone picker in a bounded container to window large lists automatically. A picker embedded in a vertical native
ScrollViewrenders inline so the parent keeps scrolling. For virtualization in that layout, give the picker the vertical viewport and pass the host’slistComponent, such as a sheet’s FlatList. Keyboard search and selection use the full filtered list.
ManagePositionBlock
ManagePositionBlock is the screen for one open position. Under the shared header it draws a BarMark and a BarPnl, the host's actions as rows, and the position itself. The two bars are read-only, so they are drawn without a card (surface={false}) and sit directly on the screen; only the things a person can press look like surfaces. It is available from @bloxwap/hig/react/blocks/manage-position-block, @bloxwap/hig/native/manage-position-block and the blocks aggregates.
<ManagePositionBlock labels={t.position} mode="Demo" side="long"
entry={64700} mark={64696} liquidation={63082} margin={10} notional={399.98}
actions={[{id: 'stop-loss', label: t.stopLoss, onSelect: openStopLoss},
{id: 'take-profit', label: t.takeProfit, onSelect: openTakeProfit},
{id: 'close', label: t.close, onSelect: openClose}]}
position={{name: 'Bitcoin', icon: btc, leverage: 40, size: 0.006182, pnl: -0.0247, pnlPercent: -0.0025}}
onBack={goBack}/>- Labels. Every word in this block is a trading term, so the host supplies all of them through
labels:title,margin,notional,liquidation,mark,entry,long,short, and one sentence that receives a formatted figure,toLiquidation(percent). HIG ships no default text here, in keeping with the rule that built-in strings contain no glossary term. - Margin bar. The first element is a
BarMarktitled with the margin mode frommode(Demo, Cross, Isolated), or the margin label without one, and reads the share left before liquidation on its trailing edge, for example 99.8% to liquidation. Its bar is the margin in the info role against the rest of the notional in the positive role, so a 40× position shows a one-fortieth sliver of margin. The legend names both with their dollar amounts. - Price bar. The second element is a
BarPnl(see the financial data chapter): one bar that places the liquidation, mark and entry prices, coloured by whether the position is in profit or loss, with the three prices under it in price order. It takes its three labels fromlabels.liquidation,labels.markandlabels.entry.positionCorridor({side, entry, mark, liquidation})still returns the share left before liquidation that the first element shows. In profit the bar and the mark price take the positive role and the first element reads 100% to liquidation; the catalog'sprofitexample shows it. - Prices. The three prices are drawn compact, with no extra zeros:
$64,700,$142.96,$0.4821.priceOptionschanges the format, for example to another currency. - Actions. Each action is
{id, label, onSelect}plus optionaldisabled. Together they are oneListGroup: rows with a chevron that share one rounded container, such as Stop Loss, Take Profit and Close. The host supplies the labels and opens its own flow. - Action values. An action can take a trailing
valuebefore its chevron: host text, or a live figure{value, options, prefix, suffix}that updates place by place.tonecolours itpositive,negativeormuted(the default is the muted value colour). Use it for a resting order on the row that manages it, such as a take profit set at $66,000. The row reads its label and value as one button. - Position.
position={{name, icon, leverage, size, pnl, pnlPercent}}draws the row under the actions: artwork, the name over an arrow for the side with the leverage and size, and profit and loss in dollars over its percent. The arrow and the profit and loss take the positive role for long and gain, and the negative role for short and loss; the arrow's meaning is also read out fromlabels.longorlabels.short, so colour is never the only signal. - Position extras. All optional, all host text.
badgedraws a small badge after the name, such as a venue.captionis one muted line 8 units under the row, for a result that is stale or estimated.onSelectwithlabelmakes the whole row one button, for example to open the market: it is named bylabelfollowed by what the row shows (View Bitcoin, Bitcoin, Long, 40×, -$0.0247), so the figures are read even with hints turned off, and the caption is its description (native: its hint). - Artwork and initials.
symbolis the short ticker the disc shows when there is no artwork (BT); without it the disc shows the first three letters of the name. AniconURL that fails to load falls back to the initials on both platforms.iconcan also be a function that draws a host element and receivesfailed, for artwork the block cannot watch itself, such as an SVG component:icon: failed => <MarketIcon symbol='BTC' onError={failed}/>. Once it is called the disc showsiconFallback, a host element, or the initials without one, until the artwork changes. - Profit and loss format.
pnlOptionsis merged over the default format of the dollar figure (signed US dollars, up to four decimals), for example{maximumFractionDigits: 3}for a host's own decimal ladder. The provider'snumberFormatstill applies under it. - Heading id.
headingIdis passed to the header, as onScreenHeader. - Pinned header.
stickyHeaderpins the header (see pinned headers); native also takesstickyHeaderBackgroundandscrollComponent. - Live numbers. The share to liquidation, the three prices, the size, the profit and loss and figure values on the actions update through
NumberFlow. - Ownership. The block never reads a position, a price feed or an account, and never places an order.
TargetBlock
TargetBlock sets a take profit or a stop loss on one open position. kind chooses which: take-profit takes the positive role and stop-loss the negative role, for the bar, the trigger price, the selected quick choice and the confirming action. It is available from @bloxwap/hig/react/blocks/target-block, @bloxwap/hig/native/target-block and the blocks aggregates.
<TargetBlock kind="take-profit" labels={t.takeProfit} position="BTC · Long 40×" orderType={t.takeLimit}
note={t.takeLimitNote} entry={64699.5} trigger={quote.trigger}
unit={unit} onUnitChange={setUnit} value={target} onValueChange={setTarget} presets={[1, 2, 5, 10]}
onCustom={openEntry} onCancel={goBack} onSubmit={placeOrder} onBack={goBack}/>- Labels. The host supplies the trading words through
labels:title,submit,entry,trigger,custom,unit(the name of the unit control) andunits(dollar,price,percent).canceldefaults to the built-in Cancel.presets(0.8.0) names the quick choices, not drawn, and defaults totitle(web: therole="group"'s name; native: each chip's hint). - Target.
valueis the target in the currentunitand is the headline figure: signed dollars of profit or loss (2reads +$2.00,-0.5reads -$0.50), a price, or a signed fraction (0.05reads +5%).nullreads as unknown and disables the confirming action. - Prices. One chart replaces a list of label and value rows, and it sits directly on the screen with no card around it. Its title is
position, host text such as BTC · Long 40×, and its trailing text isorderType, such as Take-limit. The bar under them has two points, the entry price and the trigger price, and is a fill in the role colour at half strength between them, with the trigger edge in the role colour. The two prices read under the bar in price order, with the trigger in the role colour. The mark price is not part of this block: the question it answers is how far the trigger is from entry.targetLayout({entry, trigger})returns the same positions for a host-drawn view.surfacedraws it inside a card (fill, padding and radius), the same setting asBarMarkandBarPnl, where it defaults to on. - Trigger.
triggeris the price the order triggers at. The host derives it from the target, because that needs the position size and the fee model. In thepriceunit it defaults tovalue. Until it is known the bar has no stretch and the trigger reads as the unknown dash. - Note.
noteis one sentence about how the order fills, such as that a take-limit fills only at the target price or better. Withlabels.info, the accessible name of the button, an info button sits on the trailing edge of the header and opens the sentence in a popover under it. Pressing the button again, pressing anywhere else or, on web, Escape closes it. The popover is the block's own, so the web entry needs no Radix peer, and native draws the same popover. Withoutlabels.info, or whenheaderActiontakes the trailing edge, the sentence is always shown under the headline figure. Leavenoteout and there is no button, as on a stop-market order. - Unit.
unitslists the units offered, all three by default, as aSegmentedControl;onUnitChangereports the choice. With one unit the control is hidden. The host convertsvalueandpresetswhen the unit changes. A unit can be{unit, disabled}to show it dimmed when it cannot be chosen now, for example Price while the size is zero. - Quick choices.
presetsare values in the current unit, drawn as equal capsules in one row by the publicPresetGroup(selection), selected in the kind's colour. Whole dollar amounts drop their cents (+$1, -$0.50), and so do whole prices (0.8.0:$63,000even whenpriceOptionsfix two fraction digits; a price formatted by significant digits keepspriceOptions), on web and native alike. On native each label is one line that shrinks to fit its column (down to 75%) rather than wrapping. The preset equal tovalueis shown selected and exposed as pressed;onValueChangereports a press on another preset (0.8.0: a press on the selected one no longer reports it again, and a new choice plays the provider'sselectionfeedback instead ofactivate). A preset can be{value, disabled}to show it dimmed, for example a stop inside a fee floor; the host explains why.targetPresetsandtargetUnitsreturn either list in its object form.onCustomadds a Custom row with a chevron above them, and the host opens its own entry, for example a keypad sheet. - Custom value.
customValueis the value the host's entry set, in the current unit. The Custom row then shows it on its trailing edge, is filled like a selected quick choice (the action colour for a take profit, the negative colour for a stop loss, with the label, value and chevron in the colour drawn on that fill) and is exposed as pressed (native: selected), and no quick choice shows selected. Its accessible name is the label and the value. - Money format. Dollar presets, the custom value and the headline follow the provider's
numberFormat, so{currencyDisplay: 'narrowSymbol'}reads+1 $in French. Percentages are not currencies and keep Intl's percent format. - Actions.
onSubmitis the confirming action, labelled bylabels.submit, withbusyandsubmitDisabled.onCanceladds Cancel beside it.onBackandheaderActionare the header controls, as inAccountBlock.headerActionBesideInfokeeps the info button whenheaderActionis given: the info button comes first and the host control sits on the trailing edge, and both header sides widen to 92 units so the title stays centred. Without itheaderActionreplaces the info button, as before.headingIdis passed to the header. - Live numbers. The headline figure and the three prices update through
NumberFlow. - Pinned header.
stickyHeaderpins the header (see pinned headers); on native the block becomes its own scroll view and the info popover opens just under the pinned header. - Ownership. The block never reads a position or a price feed and never places an order.
PresetPickerBlock
PresetPickerBlock chooses one value from quick choices, such as a trade sheet's Size or Leverage pane: an optional header, the value as the headline figure, an optional row that opens the host's own entry, the choices as chips, then Cancel and the confirming action. It reuses TargetBlock's parts (the headline, the Custom row, PresetGroup and the actions row) without the price card and the unit control. It is available from @bloxwap/hig/react/blocks/preset-picker-block, @bloxwap/hig/native/preset-picker-block and the blocks aggregates.
<PresetPickerBlock<'max' | number>
value={notional} valueOptions={{style: 'currency', currency: 'USD', maximumFractionDigits: 0}}
presets={[{value: 'max', label: 'Max'}, {value: 25, label: '$25'}, {value: 100, label: '$100', disabled: 100 > maxUsd}]}
selected={maxed ? 'max' : steps.includes(notional) ? notional : null} onPresetChange={choose} presetsLabel="Size" columns={3}
custom={{label: 'Custom amount', value: custom ? '$75' : undefined, onSelect: openKeypad}}
submitLabel="Set Size" onSubmit={done} onCancel={restore}/>- Header.
titledraws the sharedScreenHeader, withonBack,backProps,headerAction,headingIdandstickyHeaderas in the other blocks. Leavetitleout for a pane whose host draws its own header (as a sheet that keeps one header across its panes does): the block then starts at the headline figure. NativestickyHeaderneedstitle, and takesstickyHeaderBackgroundandscrollComponent. - Headline.
valueis the value being chosen, drawn asTargetBlock's headline figure throughNumberFlow, formatted withvalueOptions, withvaluePrefixandvalueSuffix(such as×for leverage) and read withvalueLabelbefore it.nullreads as unknown. A host with its own number table passesformattedValue, its own text for the figure ($1,250.50), drawn and read in place of the formattedvalueasNumberFlowformattedValuetakes it (static, unlessanimateFormattedrolls its digits in place);valuestill decides known or unknown. - Quick choices.
presetsarePresetGroupoptions,{value, label, disabled?, testID?}, with host labels ($25,Max,40×) and string or number values.selectedis the chip shown selected, kept apart fromvalueso a sticky Max or a custom value can select a chip or none;onPresetChangereports a press on another enabled chip.columnssets chips per row,presetsLabelnames the group (defaulttitle), and the selected chip takesintent(primaryby default, ordestructive). - Custom row.
customaddsTargetBlock's Custom row above the chips:{label, onSelect}, plusvalue(host text drawn on the trailing edge; the row is then filled like a selected chip and reads as pressed, native: selected),selected(defaults to whethervalueis given),accessibilityLabel(webaria-label, nativeaccessibilityLabel, in place of the label and value),testIDand, on native,pressProps(Pressable props for the row, such as{android_disableSound: true}for a host that plays its own sound; HIG keeps its own name, role, state and press). The host opens its own entry, such as a keypad, ononSelect. - Adjustable (native).
adjustable={{incrementLabel, decrementLabel, testID?}}wraps the chips in oneaccessibleadjustableview (the chips inside are then one element to VoiceOver and TalkBack) named bypresetsLabeland valued by the selected chip's label: the screen reader's adjust gesture steps to the next or previous enabled chip and reports it throughonPresetChange. With any ofmin,maxornowinadjustable, the value is reported asaccessibilityValue={{min, max, now, text}}(nowdefaults to the selected chip's value when it is a number,textstays its label), so TalkBack and VoiceOver can place the value in its range; without them it stays{text}. Web chips are already buttons in the tab order. - Between.
childrenare drawn as given between the chips and the actions, such as a muted note. - Actions.
onSubmitwithsubmitLabelis the confirming action inintent, withsubmitDisabledandbusy;onCanceladds Cancel on its leading side (cancelLabel, default the built-in “Cancel”), the two sharing the row equally as inTargetBlock.suppressFeedbackkeeps the provider's feedback off the chips and both actions for a host that plays its own cue. - Test IDs. Web:
submitTestID,cancelTestID,custom.testIDand each preset'stestIDbecomedata-testids, and other attributes, such as adata-testidfor the block, pass to its<section>. Native:testID(defaultpreset-picker) prefixes-header,-back,-title,-headline,-custom,-custom-value,-presets,-preset-<value>(a preset without its owntestID),-adjustable,-actions,-canceland-confirm;custom.testIDandadjustable.testIDreplace theirs. - Ownership. The block holds no value of its own: the host keeps the value, restores it on Cancel and commits it on the confirming action.
PositionBlock
PositionBlock is the sheet for the position being opened or edited. Under the shared header, with Close on its trailing edge, it shows a summary, an optional paper trading switch, and the settings as grouped rows. It is available from @bloxwap/hig/react/blocks/position-block, @bloxwap/hig/native/position-block and the blocks aggregates.
<PositionBlock title={t.position} onClose={close}
details={[{label: t.notional, value: {value: 400, options: wholeDollars}},
{label: t.fee, value: {value: 0.53, options: dollars}, tone: 'negative'},
{label: t.liquidation, value: {value: -0.025, options: percent}, tone: 'negative'}]}
paperTrade={{label: t.paperTrade, checked: paper, onCheckedChange: setPaper}}
groups={[[{id: 'size', label: t.size, value: '$10', onSelect: openSize},
{id: 'leverage', label: t.leverage, value: '40×', onSelect: openLeverage}],
[{id: 'positions', label: t.positions, value: '2', onSelect: openPositions}]]}/>- Words. Every label is host text, because built-in strings carry no trading terms; only Close and Back are built in.
- Summary.
detailsare label and value lines in the order given. They sit directly on the screen, with no card, on the same text inset as the list rows below. Values use the interface face at one weight, so host text and figures read alike. A value is host text, such as 2% of profit, or a figure{value, options, prefix, suffix}that updates place by place throughNumberFlow; anullfigure reads as unknown.tonecolours the valuepositive,negativeormuted, for a fee or a liquidation distance. The label always carries the meaning, so colour is never the only signal. - Waived values.
struckon a detail draws its value struck through, for a charge that does not apply, and is the host word read after it, such as Waived: the line reads Fee, $0.53, Waived. The line is drawn over the value, so it crosses a live figure too. Pair it withtone: 'muted'. - Label accessory.
labelAccessoryis host content right after a detail's label, such as a badge with a popover that explains a reduced fee. It may be interactive: on native the line is then no longer one accessibility element; the label reads the line and the accessory follows as its own element. - Note.
noteis one sentence, such as the minimum margin. It is the summary's footnote: small muted text 8 units under the summary, on the same inset. - Paper trading.
paperTrade={{label, checked, onCheckedChange}}adds a switch as a row of its own above the settings. The host names it and owns its state, and usually changesdetails,noteandgroupswith it: a paper position might charge a share of profit and offer no stop loss.disableddims it. The whole row is the target: on web a press anywhere on the row that is not on a control presses the switch once, through the switch, so its feedback runs as usual; on native the row is one switch. - Paper trading action.
paperTrade.action={{label, onSelect, intent, busy, disabled}}draws a full-width button on the row's card, 8 units under the switch and 16 from the card's bottom, for example to collect what a paper position earned.intentisprimary(the default),secondaryordestructive, such as for a second press that confirms. Pressing it does not toggle the switch. It is a HIGButton, so on web it draws the provider'spressDecorationas a'button', like every block action. - Settings.
groupsis a list of groups, and each group is oneListGroup: rows that share a rounded container, 24 units from the next group, the standard gap between list groups. A row is{id, label}plus an optionalvalueon the trailing edge: host text or a live figure{value, options, prefix, suffix}that updates place by place. Any number a row shows can be a figure, not only money: Leverage is{value: 40, suffix: '×'}and Positions{value: 2}, so they move place by place too. WithonSelectthe whole row is a button with a chevron and the host opens its own view, for example aTargetBlockfor Stop Loss; without it the row is static. WithonCheckedChangeandcheckedthe row is a switch named by its label, toggled from anywhere on the row like the paper trading row; itsvalue, if any, sits before the switch.disableddims a row. An empty group is not drawn. - Header.
onCloseshows Close on the trailing edge;headerActiontakes its place.onBackshows Back.headingIdis passed to the header.backPropsandclosePropspass attributes (web) or Pressable props (native, such asandroid_disableSound) through to Back and Close. - Pinned header.
stickyHeaderpins the header with the shared behaviour described under pinned headers: transparent at rest, filled once content scrolls under it. On native the block then becomes its own scroll view. The header can also be drawn on its own for a host scroller: renderPositionBlockHeader(the sametitle,onClose,onBack,headerAction,headingId,backPropsandcloseProps, plusstyle) as a sticky header of that scroller, pass itscrolledfromuseStickyHeaderScroll()so it fills the same way, and renderPositionBlockwithheader={false}under it. The two stack exactly as the whole block does. - Ownership. The card never reads an account, computes a fee or places an order.
TradeHistoryListBlock
TradeHistoryListBlock is the history of closed trades as one screen: the same header as AccountBlock, then one capsule row per trade, 8 units apart. It is available from @bloxwap/hig/react/blocks/trade-history-list-block, @bloxwap/hig/native/trade-history-list-block and the blocks aggregates.
<TradeHistoryListBlock labels={t.history} trades={closed} onBack={goBack}
onSelect={trade => open(trade.id)}/>-
Labels.
labelssuppliestitle,long,shortandempty, and optionallyemptyDescription. They are trading terms, so HIG ships none. -
Trades. A
TradeHistoryItemis{id, name, side, pnl}plus optionalicon,symbol,leverage,leverageNote,timeandtag.iconis round artwork: an image URL or a host element; without it the row showssymbol, or the first letters of the name.timeis host-formatted text such as2d.tagis small muted host text before the age, such as the wallet a trade came from (0x22…22 · 2d), and is read after the result. Rows keep the host's order; the host sorts and pages them. -
Side. Under the name an arrow points up for a long and down for a short, followed by the leverage (
20×), in the marketuprole for a long and thedownrole for a short, the same rolesTradeHistoryDetailBlockuses. They default tobuyandsell; a host whose market convention differs setsHIGProvider marketColorson either platform (see market direction colours). Assistive technology reads the host's word for the side.leverageNoteis a short muted qualifier after the leverage, read with it, for leverage that was not recorded with the trade:20× current. -
Result.
pnlis the net profit and loss in dollars, signed, in theuprole for a gain and thedownrole for a loss;nullreads as unknown. The default format is four significant digits (+$1.412,+$17.90,-$0.6878);pnlOptionschanges it on web and native, and the provider'snumberFormatis merged under it. A trade's ownpnlOptionswins over the block's, for a host whose decimal ladder depends on the amount, such as more digits under one cent. The figure updates place by place. -
Selection.
onSelectmakes each row one button that reports its trade, for example to openTradeHistoryDetailBlock, and shows a disclosure chevron. Without it the rows are not interactive. -
Empty. With no trades the block shows
labels.emptyunder the header, withlabels.emptyDescriptionas a muted second line when given. The empty line (and anerrorin its place) keeps 32 units above it and none below, so the block's 16-unit inset is the only space under the text (0.8.0: it also kept 32 below, which left 48 under the text in a sheet). -
Loading and failure.
loadingdraws four skeleton rows in place of the trades and marks them busy;loadingLabelis host text that names and announces them.erroris host text in place of the rows, in the negative role and announced. The header stays in place in both. -
Notice and footer.
noticeis host content under the header and above the rows, such as a partial-history notice or a mode banner.footeris host content under the rows, such as paging or a spinner for the next page. Both sit 16 units from their neighbours, the block's gap. -
Long lists (native). The block draws every row it is given. For a long history,
renderListhands the rows to the host's own list: it receives{trades, renderItem, keyExtractor, ItemSeparatorComponent}, shaped forFlatList, sorenderList={list => <FlatList data={list.trades} {...list} initialNumToRender={10}/>}mounts only the rows near the screen and keeps the 8 unit gap. By default the header,noticeandfooterstay fixed around the list, in the block's own 16 unit inset. AddlistChromeand the list carries everything around the rows instead: it also receivesListHeaderComponent(the header andnotice, 16 units above the first row),ListFooterComponent(thefooter, 16 under the last) andcontentContainerStyle(the 16 unit inset), and the block adds no padding of its own, so everything scrolls together, a sheet that sizes itself to its content measures the list alone and needs no offsets of its own, and a notice that appears later is just part of the list. WithlistChrome, spread the whole object; picking onlyrenderItemleaves the header out. WithrenderListthe block fills its parent (flex: 1), so place it in a bounded container such as a sheet body, not inside aScrollView. A sheet library's list (for example a bottom sheet'sFlatList) works the same way. Loading, an error and the empty state are drawn by the block as usual. -
Header.
onBackshows Back andheaderActionis the trailing control, as inAccountBlock. -
Pinned header.
stickyHeaderpins the header (see pinned headers). On native withoutrenderListthe block becomes its own scroll view; withrenderListthe header stays above the host's list (withlistChrome,ListHeaderComponentthen carries only the notice), and the list getsonScrollandscrollEventThrottleso the header fills once rows scroll under it. -
Long histories. React windows histories above 50 trades in the existing page or container scroller. On native, a large sticky history uses a FlatList automatically. A host that owns the vertical list can supply it through
renderList.
TradeHistoryDetailBlock
TradeHistoryDetailBlock is the full record of one closed trade. Under the shared header it shows the asset with its side and leverage on one line, the net result as the headline figure with the return on margin under it, one bar from the entry price to the exit price, the trade's other figures as a compact grid, and the host's actions in one row. Nothing above the actions is pressable, so none of it is drawn as a card: it sits directly on the screen. It is available from @bloxwap/hig/react/blocks/trade-history-detail-block, @bloxwap/hig/native/trade-history-detail-block and the blocks aggregates.
<TradeHistoryDetailBlock labels={t.trade} name="Amazon" icon={amzn} side="short" leverage={20}
pnl={1.418} pnlPercent={0.0284}
entry={267.6} exit={267.18}
details={[{label: t.size, value: 3.734, suffix: ' AMZN'}, {label: t.notional, value: 999.23, options: usd},
{label: t.held, value: '38m 20s'}]}
actions={[{id: 'save', label: t.saveImage, onSelect: saveImage},
{id: 'share', label: t.share, intent: 'primary', onSelect: share}]}
onBack={goBack}/>- Labels.
labelssuppliestitle,long,short,entryandexit(the names of the two prices under the bar), one sentence that receives a formatted figure,onMargin(percent), andnetPnl.netPnlnames the figure for assistive technology and is not drawn: on screen the signed figure and the sentence under it carry the meaning. The detail figures and the actions carry their own labels. HIG ships no trading terms. - Asset. One centred line shows a small disc with the artwork (
iconas an image URL or a host element, elsesymbolor the first letters of the name), thename, an arrow and the side word in the marketuprole for long and thedownrole for short, and theleverageas20×, followed by the mutedleverageNotewhen given. - Result.
pnlis the headline figure, signed, in theuprole for a gain and thedownrole for a loss;nullreads as unknown.pnlOptionsformats it (default: signed US dollars, up to four decimals), and the provider'snumberFormatis merged under it, so{currencyDisplay:'narrowSymbol'}makes French read+12,50 $.pnlPercentis the return on margin as a fraction and reads inside the host's sentence, for example +2.84% on margin;percentOptionsformats it (default: a signed percent with two decimals). LeavepnlPercentout to hide the line. - Details.
details=[{label, value, options, prefix, suffix, formattedValue}]draws one row each, in the order given. A number is formatted withoptionsbetweenprefixandsuffix, or drawn as the host'sformattedValue, and moves place by place; a string is drawn as given, which suits a duration the host has already formatted. - Note.
noteis one muted sentence under the details, such as that part of the record is missing. - Badge.
badgeis short host text in a badge beside the title, such as Demo, read as part of the heading after a pause (Trade, Demo).ScreenHeadertakes the samebadge. - Capture.
summaryRefis a ref to the asset line, the headline figure and the return: on web the summary element, on native aViewdrawn around them only when the ref is passed. A host that saves the trade as an image captures that, without the details, actions or Back. The summary has no fill of its own, so an image of it is transparent:summaryBackgroundfills it,truewith the background role or a colour such as the sheet's (var(--hig-overlay)on web,useColors().overlayon native). - Pinned header.
stickyHeaderpins the header (see pinned headers). - Actions.
actions=[{id, label, onSelect, intent, disabled, busy}]draws the buttons in one row with equal widths, 8 units apart and 16 below the details.intentdefaults tosecondary; setprimaryon the one that matters, such as Share. - Ownership. The card never reads trade history, renders an image or opens a share sheet. The host does each of those when an action reports a press.
RewardBlock
RewardBlock is the screen for a trading competition. Under the shared header it shows an optional promotion, an optional choice between standings, the viewer's own standing pinned on a tinted row, and the ranked list. One block covers both a prize pool that fills towards a goal and a sweepstakes with a top prize; the promotion's fields decide which. It is available from @bloxwap/hig/react/blocks/reward-block, @bloxwap/hig/native/reward-block and the blocks aggregates.
<RewardBlock title={t.leaderboard} onBack={goBack} headerAction={share} verifiedLabel={t.verified}
promo={{eyebrow: t.season, rules: {label: t.rules, onSelect: openRules},
amount: 4037, goal: 250000, caption: goal => t.ofPrizePool(goal),
headline: t.topTradersSplit, description: t.poolFunding}}
you={me} entries={standings}/>- Words. Every word is host text; only Back is built in.
- Promotion.
promodraws one quiet card: theeyebrowin muted small capitals,rulesas a text link with a chevron on its trailing edge,amountas the one large figure in the action colour, the same size as theSwapBlockamount and theTargetBlockfigure, updating place by place, andcaptionas the line under it.headlineanddescriptionread as one paragraph: the headline in the text colour, the description continuing it in the muted colour.actionis a quiet row at the foot of the card, under a hairline, with its label in the muted colour and a chevron on the trailing edge, for example to the draws. It is not a filled button: the card promotes the prize, and the row is a way onward. Leavepromoout for standings alone. - Prize pool. With
goal, a thin progress bar filled toamount / goalsits under the caption, and acaptionfunction receives the formatted goal:goal => 'of ' + goal + ' prize pool'. The bar carries the progress on its own; there are no lines under it.rewardProgress(amount, goal)returns the same share. - Sweepstakes. Without
goalthere is no bar, andcaptionis a string under the figure, such as top prize. - Host figures and captions.
promo.amountmay be host text, such as'$500'already formatted: it is drawn as given in the figure's style (webp.hig-reward-amount; native in the positive colour, read with a text caption).promo.figureis a headline slot: host content drawn in the figure's place in place ofamount(webdiv.hig-reward-amount, which gives it the figure's type; native<testID>-figure, drawn as given and read as it reads itself).caption(or what acaptionfunction returns) may be any node, such as a live countdown: web draws it indiv.hig-reward-caption; native draws it after the figure as its own element (<testID>-caption), not folded into the figure's reading. Leave outamountandfigurefor a promotion with no figure. A host-text amount or a figure leaves agoalbar empty. - Promotion only.
entriesis optional: without it (or with[]and nolistTitle/scoreTitle) no list is drawn, for a pane that is only the promotion. - Money.
amountOptionsformatsamountandgoal; the default is whole US dollars. - Standings choice.
tabs={{label, options, value, onValueChange}}adds aSegmentedControl, such as Upcoming draw and Top winners. The host swapsentrieswhen it changes. - Your standing.
youis the viewer's entry, pinned above the list on a tinted row with the name and score in the action colour. An entry in the list withyou: truegets the same colours in place.youLabelnames the pinned row for assistive technology, such as Your rank: on web it is a named group, on native it is read before the rank. - Status.
statusis a muted line between the pinned row and the list, announced when it changes, for a message about the standings such as not ranked yet or failed to load. - Entries. An entry is
{id, rank, name, score}plus optionalavatar(an image URL or a host element; the name's first letters otherwise),verified,detailandscoreOptions.detailis the line under the name such as the volume: host text, or a live figure{value, options, prefix, suffix}that updates place by place. The host ranks and pages them.scoreOptionsformats the scores; the default is a whole number, and an entry's ownscoreOptionswins, so a prize list can show cents only where a prize has them. Scores update place by place. - Verified.
verifiedshows a mark after the name.verifiedLabelnames it for assistive technology; without it the mark is decorative.verifiedMarkis host artwork in place of the built-in mark, drawn inside the mark's image role on web and inside the row's one accessible element on native. When the mark is a control, such as a badge that opens an explanation, addverifiedMarkInteractive: the mark then stays in the accessibility tree. On web it sits afterverifiedLabel(read, not drawn) instead of inside an image role. On native the row's reading moves from the whole row to the name, and the mark follows as its own element; the rest of the row is unchanged. - Row action (0.10.1). An entry's
actionmakes its whole row one control, for a row that leads somewhere, such as the viewer's own row opening their place on another page. Set it onyou, on the entry in the list, or on both; each row acts on its ownaction. On webaction={{label, href, target, onSelect}}draws the row as a real link (a.hig-reward-row, withrel="noopener noreferrer"for_blank) and still callsonSelecton the press;action={{label, onSelect}}draws a button (button.hig-reward-row). It takes keyboard focus with the list row's inset focus ring, presses and hovers to the nested fill (a deeper tint on the pinned row), and carries the provider'spressDecorationfor rows. On native the row is aPressablethat presses to the same fills: a button withonSelect, or withhrefa link (accessibilityRole="link") that opens the URL throughLinking.openURLunless the host passesonSelectto open it itself.labelis not drawn. It names the action after the row's own reading, so the control reads as its rank, name, verified words, detail and score and then the label (2, you, $1,090,779 vol, 418,450, Open your place on PrizeRail), withyouLabelstill naming the pinned row's group on web and leading its reading on native. Nothing marks the row as a control beyond its hover and pressed states, so say where it leads in the surrounding text if that matters. A row withoutactionis drawn and read exactly as before. In a windowed list (more than 50 entries on web) a row with an action stays reachable by Tab from either end. - Row action with an interactive mark. A control cannot hold another control, so a row that has both an
actionand an interactiveverifiedMarkkeeps the mark as its own control. On web the row stays a plain element (.hig-reward-row[data-action]) and the link or button (.hig-reward-hit) covers it, named as above, with the mark above it and before it in the Tab order. On native the row takes the press without being one accessible element, the name carries the reading, the role and the action for assistive technology, and the mark follows as its own element. - Headline.
promo.headlineis host text, or host elements, for example to accent words in the action colour:headline: <>Top 100 <Text style={{color: colors.action}}>split the pool.</Text></>on native, or a<span>with the host's own class on web. The block wraps it in the semibold text-coloured run and puts one space anddescriptionafter it, so the host translates the whole sentence and decides where the accent falls; keep any closing punctuation inside the elements. - Links (web).
promo.rulesandpromo.actiontakehref, andtargetsuch as_blank: they then render as real links (<a>, withrel="noopener noreferrer"for_blank) with the same look, andonSelect, now optional, is still called on the press. On native they stay buttons; the host opens the URL inonSelect. - Loading.
loadingdraws five skeleton rows in place of the list and marks the block busy;loadingLabelis host text that names and announces them. Pass the promotion'samountasnullwhile it loads. - Paging.
pagination={{previous, next, label}}sits under the list: Previous and Next as secondary buttons ({label, onSelect, disabled}) with the host's range, such as 1–25, between them, announced when it changes. - Long standings. Web windows more than 50 entries. Native sticky screens window more than 50 loaded entries. In a bounded native sheet, pass its FlatList as
listComponentso the promotion, standings, and pagination share one scrolling list. Useheader={false}when the sheet supplies its own heading. - Sticky header.
stickyHeaderkeeps the header at the top while the standings scroll, with the shared behaviour under pinned headers: transparent at rest, so a glow the host draws behind the title shows through, and filled once the standings scroll under it. On native the block becomes its own scroll view with the header as its sticky first child;stickyHeaderBackgroundis the fill andscrollComponentswaps in a sheet library's scroll view. Place it in a bounded container. - Host header.
header={false}leaves the header out, for a host that pins its ownScreenHeaderabove the block (for example in a sheet's fixed header). The content then starts at the block's top edge, andtitle,onBackandheaderActionare not drawn. - Test IDs (native).
testIDprefixes every test ID inside the block:<testID>-header,<testID>-back,<testID>-title,<testID>-row-<id>,<testID>-youand so on. Without it they start withreward, as before, so two blocks on one screen can be told apart. - Columns and footnote.
listTitleandscoreTitleare small capitals over the names and the scores.footnoteis a line under the list and the paging. - Ownership. The card never computes a rank, fetches standings, or runs a draw.
SoundHapticsBlock, SignalsBlock and NotificationsBlock
Three settings screens share one anatomy: the shared header, then settings as cards. Each setting is a switch whose whole row is the target, with the label on the leading edge, an optional description under it, and the track on the trailing edge. The label names the switch and the description describes it. Every word is host text; only Back is built in. They are available from @bloxwap/hig/react/blocks/sound-haptics-block, blocks/signals-block and blocks/notifications-block, the matching @bloxwap/hig/native/<name> entries, and the blocks aggregates.
<SoundHapticsBlock title={t.soundHaptics} onBack={goBack} sections={[
{id: 'effects', label: t.effects, checked: effects, onCheckedChange: setEffects,
volume: {label: t.volume, value: volume, onValueChange: setVolume}},
{id: 'mic', label: t.micInput, checked: mic, onCheckedChange: setMic, source: device.name, level: inputLevel,
volume: {label: t.micVolume, value: micVolume, onValueChange: setMicVolume}},
{id: 'haptics', label: t.haptics, checked: haptics, onCheckedChange: setHaptics}]}/>
<SignalsBlock title={t.signals} verifiedLabel={t.verified} onBack={goBack} groups={[
{id: 'trend', title: t.trend, help: {label: t.howItWorks, onSelect: explainTrend},
items: [{id: 'trend', label: t.trend, description: t.trendAbout, checked: trend, onCheckedChange: setTrend}]}]}/>
<NotificationsBlock title={t.notifications} onBack={goBack} items={[
{id: 'push', label: t.push, description: t.pushAbout, checked: push, onCheckedChange: requestPush, error: pushError}]}/>- SoundHapticsBlock.
sectionsdraws one card per channel, 8 units apart:{id, label, checked, onCheckedChange}plus optionaldescriptionanddisabled. A channel that is on can show more under its switch, in this order:source, the device in use;choices, a radio group for picking the device ({label, options, value, onValueChange}, such as Automatic and each microphone);level, a live input level from 0 to 1 drawn as a thin meter (nullis empty); andvolume, fixed steps as equal capsules with the chosen one in the action colour. They are hidden while the channel is off. - Level meter. The meter is decorative and hidden from assistive technology unless
levelLabelnames it, such as Input level. It is then a meter (webrole="meter", nativeprogressbar) that reads the level as a percentage when focused. - Volume steps.
volume={{label, value, onValueChange}}uses fractions:0.25reads 25%.optionsreplaces the default 25%, 50%, 75% and 100%.labelis drawn above the steps and names the group. WithvolumeWhenOff: 'disabled'the steps stay in place while the channel is off, unavailable, instead of being hidden.soundLevel(level)returns the clamped meter share. - Section action.
action={{label, onSelect, disabled, feedback}}is a secondary full-width button at the foot of the card, 16 units below the content above it, shown whether the channel is on or off, such as Open Settings when the system refused the microphone. Like anyButtonit plays the provider's press feedback;feedback: falsekeeps it off that one button, for a host that plays its own cue for it, so the host need not take the provider's feedback away from the whole block. - SignalsBlock.
groupsare families of signals:{id, title, items}plusverified, which shows a mark after the title (verifiedLabelnames it,verifiedMarkreplaces it with host artwork), andhelp={{label, onSelect, ref}}, a small pill on the trailing edge of the heading (withverifiedMarkInteractivea controlverifiedMarkstays in the accessibility tree, as inRewardBlock: on native the heading then sits on the title text and the mark follows it), such as How it works. It is the same 32-unit pill the swap card uses, with a full-size touch target around it.refreaches the pill, so the host can return focus to it when its explanation closes (webfocus(), nativeAccessibilityInfo.setAccessibilityFocus). A group'sitemsare switches that share one rounded container, 2 units apart; an item'shintanderrorsit inside its card, under the switch. - NotificationsBlock.
itemsdraws one card per kind of notification.hintis a neutral muted line under that card, announced when it changes, for progress or a hint such as Registering this device.erroris a line in the negative role under it, announced when it appears, for a permission request that failed or timed out; the host keeps the switch off in that case.actionis a secondary button under the card, 16 units below it, such as Open Settings; it takesfeedback: falseas the section action does.groups=[{id, title, items}]draws more cards underitems, each group under an optional muted heading and 24 units from what is above it;itemsmay then be left out. - Row geometry. Separate cards are 8 units apart and a
SignalsBlockgroup's cards 2 apart, on both platforms. A setting's switch is a 48-unit target with 12 above and below its text, and its card adds 4 above and below, so a row is 56 units, 79 with a one-line description (each further description line adds 21); a card with content under its switch (a channel's body, a signal's hint or error) has 12 between them and 16 at its foot. 0.8.0 on native: the switch was 32dp in a card padded 12, so a described row measured about 72dp, a plain row's label sat 4dp high, and the switch's touch target was 32dp tall. - Locked and accessories. An item in either block takes
locked: the switch shows on at full strength and is read as unavailable (webaria-disabled, native disabled state), and presses do nothing. Use it for a signal that is always on.labelAccessoryis host content after the label, such as a badge. On web it is part of the switch's name, read after the label and a pause (a comma that is read, not drawn: Swing notifications, Genesis), so give artwork a text alternative; on native the switch is read bylabelalone.labelAccessoryLabelis host words for the accessory on both platforms, read after the label and a pause (Feed, New): native adds them to the switch's name, and web reads them in place of the accessory's content, which is then hidden from assistive technology. The accessory cannot be a control of its own: on web it sits inside the switch's<label>, whose content model allows no other labelable control and whose text becomes the switch's name (aria-labelledby), and on native the whole row is one accessible switch, so a nested control would not be reachable by a screen reader. - Pinned header.
stickyHeaderon each of the three pins the header (see pinned headers); on native the block becomes its own scroll view. - Description.
descriptionon each of the three blocks, and onLanguageBlock, is a muted line under the header that explains the screen. - State. Every switch is controlled: the host holds
checkedand decides inonCheckedChangewhether the change takes, for example after the system permission prompt.disableddims a row and blocks it. - Ownership. The blocks never play a sound, read the microphone, vibrate, request a permission or subscribe to anything.
AssetsBlock
AssetsBlock is the market chooser as one screen, usually in a sheet: the header with an optional Close, a search field, the category capsules (Filter), the All / Positions / Trend views (SegmentedControl), then the markets in sections by category. Each row shows the market's round icon, its name over its symbol and detail, and an optional signal disc on the trailing edge. It is available from @bloxwap/hig/react/blocks/assets-block, @bloxwap/hig/native/assets-block and the blocks aggregates.
<AssetsBlock onClose={close} selectedId={market.id} onSelect={openMarket}
categories={[{id: 'crypto', label: 'Crypto', status: {label: 'OPEN'}},
{id: 'commodities', label: 'Commodities', opensAt: session.commodities.opensAt}]}
assets={[{id: 'BTC', name: 'Bitcoin', symbol: 'BTC', detail: '40×', category: 'crypto', signal: 'watch', position: true},
{id: 'GOLD', name: 'Gold', symbol: 'GOLD', detail: '20×', category: 'commodities', signal: null}]}/>- Markets. Each asset is
{id, name, symbol, category}plus optionaldetail(short text after the symbol, such as the maximum leverage40×),icon(an image URL or a host element; without it the disc shows the symbol's first letters),keywordsfor search, anddisabled. A selectable row is one button named by its name, symbol line and signal. - Trailing content (0.8.0).
trailingputs host content on the row's trailing edge before the signal disc, such as the live result of the viewer's open position; it never shrinks, and the name and symbol line truncate first. It sits inside the row button and is hidden from assistive technology, sotrailingLabelgives the words the row reads after its symbol line (Bitcoin, BTC · 40×, open position, Watch). On native the content's wrapper takes the test ID<testID>-<id>-trailing. - Signal.
signalis'watch'(an eye on a warning tint),'up'or'down'(a trend arrow on a positive or negative tint), ornullfor an empty disc. Leave it out to draw no disc. The signal is read after the market (built-insignalWatch,signalUp,signalDown), so it is never colour alone. - Categories.
categoriesorders the sections and the capsules; a market whose category is not listed is not shown, and an empty section is not drawn.status={{label, tone}}puts a badge on the section heading, such as OPEN, read with the heading.toneispositiveby default. - Opening countdown. Bloxwap trades around the clock, so a section never says closed. When the legacy market behind a category is shut, pass
opensAt(epoch milliseconds or aDate) and the badge counts down to it in a neutral tone: “Opens in 2:14:33”, or “Opens in 1d 04:12:09” past a day, ticking each second. Each digit that changes rolls in place throughNumberFlow, and stays still under reduced motion or whilepaused. Native gives the countdown text the test ID<testID>-countdown-<category id>. The heading reads it in words without seconds (“Commodities, Opens in 2 hours, 14 minutes”), so the accessible name changes at most once a minute and nothing is announced on its own. The countdown takes the place ofstatuswhile it runs; onceopensAtpasses,statusshows again, so a host can pass both. On web the countdown appears after hydration, so server HTML carries no clock.formatCountdownfrom@bloxwap/hig/contractsexports the same formatting. - Section headings. A section's heading and its badge sit 8 in from the row edges, the rows' own padding, so the heading starts on the icon's leading edge and the badge ends on the disc's trailing edge, as the token pickers' section headings line up with their rows (0.8.0; before, 4 in).
- Category capsules. The capsules are left out with one category or
categoryFilter={false}; on native,filterScrollComponentreachesFilter'sscrollComponent. The capsule row scrolls out to the container's edge with a 16 inset (0.8.0,Filter bleed), so capsules are cut by the sheet edge, not by the block's padding. On native the block draws that 16 padding itself, so the row runs to the block's edge. On web the block has no side padding of its own and assumes the 16px sheet content gutter around it (--hig-filter-bleed: 16pxon.hig-assets-block); a host that places the block flush setsstyle={{'--hig-filter-bleed': '0px'}}on it, or its own gutter, so the row never overflows the page. - Views. All shows every market, Positions those with
position: true, and Trend those with a signal (notnull). Each view, the category (''is All) and the search query are uncontrolled by default (defaultView,defaultCategory,defaultQuery) or controlled withview/onViewChange,category/onCategoryChangeandquery/onQueryChange, for example to restore the last choice. The search matches name, symbol andkeywords, ignoring case and accents.clearable(0.8.0) showsSearchInput's clear button while the field holds text; it empties the query (throughonQueryChangewhen controlled) and returns focus to the field, named bymessages.clearSearch, with the native test ID<testID>-search-clear.filterAssetsexports the same filtering for a host that needs the counts. - Search timing. The field and
onQueryChangeupdate on each edit. Above 50 markets, filtering runs 150 ms after the last typed edit. Clearing the field, changing the category or view, and submitting from the keyboard apply the current query immediately. - Empty and loading. With nothing to show, the list reads
noResultsfor a search,noPositionsornoTrendfor those views, andnoItemsotherwise;loadingshows the loading text instead.emptyAction={{label, onPress, testID?}}(0.8.0) draws a secondaryButtoncentred under the empty text, only while the list is empty and notloading, such as Browse all markets on an empty Positions or Trend view;onPressis the one name on both platforms. ItstestIDis the webdata-testidand the native test ID (native default<testID>-empty-action). - Countdown clock (0.8.0). The countdown's timer runs only while a section with an opening still ahead is on screen under the current category, view and query.
nowgives the host's clock (epoch milliseconds; defaultDate.now), andpausedfreezes the countdown at the text it last showed and stops the timer and the rolling digits, for a sheet that is closed or an app in the background, even when the host re-renders after the opening has passed; unpausing reads the clock again. - Keyboard (web, 0.8.0). From the search field, ArrowDown and ArrowUp move an active row through the enabled rows of every section (it fills like a hovered row and scrolls into view), and Enter chooses it, or the only row when the arrows have not moved (with
enterChoosesFirstand a query, the first enabled row, as a search box's top hit; on native the same prop makes the keyboard's Search key choose it). Once a row has focus (by Tab or a click), ArrowDown and ArrowUp move focus to the next or previous enabled row, and ArrowUp from the first returns to the search field; typing, a new category or a new view resets it. The active row follows its asset'sid, so a live update that reorders the rows keeps it on the same market, and one that drops that market clears it without Enter falling back to another row. Focus stays in the field, as inLanguageBlockand the token pickers, and the active row's name is spoken through a polite live line (the rows are buttons, not options the field could point at witharia-activedescendant). Enter during an IME composition only commits the text.autoFocusSearchfocuses the field on mount, on web only with a hardware pointer (asLanguageBlock autoFocus), on native always (TextInput autoFocus). Each row carriesdata-asset-idwith its asset'sid, so a host or a test never depends on HIG's class names. - Selected row. The selected row (
selectedId) fills with the well; an empty signal disc (signal: null) on it, or on a pressed, hovered or active row, steps up to the raised fill so it stays visible (web--hig-fill-raised, nativeuseFills().raised). - Category capsules (native). The capsules scroll the selected one fully into view on mount and whenever the category changes (
Filterdoes this for every host), animated unless motion is reduced, through the scroll view'sscrollTo, so a hostfilterScrollComponentmust forward its ref (a sheet library's or Gesture Handler'sScrollViewdoes) and pass ononLayoutandonScroll. Right-to-left rows are left where the reader puts them. - One line per row. The name and the symbol line each stay on one line and truncate with an ellipsis (0.8.0), as
MarketRowdoes. - Header.
headingIdnames the heading (webid, native the title'snativeID), so a sheet can name itself withGestureSheet labelledBy.stickyHeaderpins the header (title and Close): on web in the nearest scroller, asScreenHeader stickyHeader; on native the block becomes its own scroll view with the header as its sticky first child, transparent at rest and filled withstickyHeaderBackground(default the background role) once content scrolls under it, inscrollComponent(a sheet library's scroll view) if given; the pinned header's test ID is<testID>-sticky-header(assets-sticky-header). - What a native host provides for the list to scroll. With
stickyHeaderthe block's scroll view takesflexGrow: 1, flexShrink: 1, minHeight: 0(0.8.0, whateverscrollComponentis), so it fills a bounded parent and scrolls inside it. It cannot bound itself: every view between the sheet's body and the block must have a height, eitherflex: 1(withminHeight: 0where a parent is itself a flex child) or a fixed height. A parent whose height follows its content, such as a plainViewwith no flex, or a content-sized sheet (GestureSheet enableDynamicSizing, which measures its custom content), lets the scroll view grow to the whole list: the sheet clips at its ceiling and nothing scrolls. UseGestureSheet contentMode='custom'with fixedsnapPoints(its content isflex: 1, flexShrink: 1, minHeight: 0) and pass the sheet's scroll view asscrollComponent(GestureSheetScrollView) so its drags hand off between the list and the sheet. Inside a vertical native scroll view withoutstickyHeader, the block is a plain column and the host owns the scrolling. - Large native lists. A standalone picker in a bounded native viewport automatically windows catalogs above 50 markets. Inside a vertical native
ScrollView, the picker stays inline. To window that layout, give the picker the viewport and passlistComponent={FlatList}. A sheet can supply its own FlatList. The title, filters, category headings and rows share one vertical scroller. AddstickyHeaderto pin the title. React windows lists above 50 rows in the existing page or container scroller. - Ownership. The block never reads a market, a position or a signal. The host passes the data and opens the market on
onSelect; on native the host can provide the vertical list throughlistComponentor wrap the inline picker in its own scroller. WithstickyHeader, the picker supplies a default scroller.
ProfileBlock
ProfileBlock is a person's profile as one screen, usually in a sheet. A top bar holds the address control on the leading edge and Close on the trailing edge, both as bare icons with no filled circle behind them, like the other block headers; under it sit the avatar with an optional status dot, the name with an optional edit control, and then the sections as ListGroups 24 units apart. It is available from @bloxwap/hig/react/blocks/profile-block, @bloxwap/hig/native/profile-block and the blocks aggregates.
<ProfileBlock name="5459····6263" address={account.address} status={{label: 'Demo'}}
onShowAddress={showAddress} onClose={close} onEditName={editName}
sections={[
{id: 'money', rows: [{id: 'accounts', label: 'Accounts', value: '$1,042.09', onSelect: openAccounts},
{id: 'history', label: 'History', onSelect: openHistory}]},
{id: 'settings', title: 'Settings', rows: [
{id: 'live', label: 'Live Mode', checked: live, onCheckedChange: setLive},
{id: 'notifications', label: 'Notifications', value: 'Off', onSelect: openNotifications}]},
]}/>- Avatar.
avataris an image URL or a host element. Without it,addresscolours the disc the way wallet avatars are coloured elsewhere; with neither, the disc shows the first letters of the name. It is 144 units across and decorative. - Avatar press.
onAvatarPressmakes the avatar a button, for example to choose a picture, named byavatarLabel(the name when left out, and the built-inchangeProfilePicturemessage, “Change profile picture”, when there is no name either). The status dot stays outside the button and is still read on its own. On web it takes the host's press decoration as an'icon-button'. - Status.
status={{label, tone}}draws a dot on the avatar's top trailing edge for an account mode or state, such as Demo.labelis read out, so the dot is never colour alone.toneiswarningby default, orpositive,negativeorinfo. - Name.
nameis the heading: a display name or an address the host has shortened.onEditNameadds the edit control after it.nameAccessoryputs host content between the name and the edit control, such as a membership badge; it stays in the accessibility tree, so an interactive badge needs its own name. - Action.
action={{label, onSelect}}draws a full-width button 16 units under the name, such as Log in for a signed-out viewer. It isprimaryby default (intent: 'secondary'for a quieter one) and takesdisabled. With an action,namemay be left out: the heading is then not drawn. - Top bar.
onShowAddressshows the address control andonCloseshows Close. Leave either out to hide it.stickyHeaderpins the top bar (see pinned headers; native also takesstickyHeaderBackgroundandscrollComponent), so Close stays reachable on a long profile.headingIdsets theid(native:nativeID) of the name heading. - Sections. Each section is
{id, title, rows}; a section with no rows is not drawn. A row is{id, label}plus optionalleading,value,tone,trailing,disabled, and eitheronSelect(the whole row is a button with a chevron) oronCheckedChangewithchecked(the row is a switch, named by its label). The host writes every label and value. - Switch rows. The whole row is the target, as in the settings blocks: a press anywhere on it toggles the switch, and the switch is still the one named control for the keyboard and assistive technology. On web the row is
ListRow's switch row and the host's press decoration covers the whole row; native switch rows were already whole-row targets. From 0.8.0 the web input is named by the row's visible label (aria-labelledby) and the switch draws no second, visually hidden copy of the label, so the name is read once instead of two or three times. - Row values.
valueis short text, or a live figure{value, options, prefix, suffix}, such as a balance, that updates place by place (nullreads as unknown).tonecolours the valuepositive,warning,negativeormuted, for a mode or state such as Live or Demo; without it the value keeps the muted value style. A selectable row is still named by its label and value. - Footer.
footeris host content under the sections, 24 units below them on the block's inset, such as the Terms and Privacy links.
<ProfileBlock action={{label: t.logIn, onSelect: openLogin}} onClose={close} sections={sections}
footer={<nav aria-label={t.legal}><Link href='/terms'>{t.terms}</Link> <Link href='/privacy'>{t.privacy}</Link></nav>}/>
<ProfileBlock name={name} nameAccessory={<GenesisBadge/>} avatar={photo} onAvatarPress={chooseAvatar} avatarLabel={t.chooseAvatar}
sections={[{id: 'money', rows: [{id: 'accounts', label: t.accounts, value: {value: balance, options: usd}, onSelect: openAccounts},
{id: 'history', label: t.history, value: t.live, tone: 'positive', onSelect: openHistory}]}]}/>- Ownership. The block never reads an account, a balance or a setting. Each control only reports the press; the host opens its accounts, history, rewards and settings screens.
ScreenHeader
ScreenHeader is the block header: Back on the leading edge, the title centred, and an optional control on the trailing edge, with the title centred whichever of the two are present. On web every block with a header draws it; on native the settings blocks (NotificationsBlock, SignalsBlock, SoundHapticsBlock) draw it and the other blocks draw a header that matches it. It has its own entry for a host pane that has no block, such as a keypad pushed from TargetBlock or a pane between two blocks, so the pane matches the blocks around it: @bloxwap/hig/react/blocks/screen-header on web and @bloxwap/hig/native/screen-header on native. The native entry also exports ChevronIcon, the glyph its Back control draws (it points down; rotate it).
import {ScreenHeader} from '@bloxwap/hig/react/blocks/screen-header';
// Native: import {ScreenHeader} from '@bloxwap/hig/native/screen-header';
<ScreenHeader title={t.editTarget} onBack={goBack} action={<IconButton label={t.done} onClick={done}>{check}</IconButton>}/>- Props.
titleis host text.onBackshows Back, named by the built-in translatedbackmessage.actionis the trailing control.badgeis short host text in a badge beside the title, such as Demo, read as part of the heading after a pause (web: inside theh2after a comma that is read, not drawn; native: one header element read astitle, badge).eyebrowis a kicker over the title, centred in small muted capitals, read before the heading as its own line (webp.hig-screen-eyebrowwith theh2in adiv.hig-screen-heading; native<testID>-eyebrow); the header grows to fit it. Withouteyebrowthe header is unchanged. - Unavailable Back.
backDisableddraws Back in the faint colour,disabled(native: read as disabled) and not pressable, for example while a close is being signed; on web it draws no press decoration. - Control props.
backPropspasses attributes to the Back<button>on web, or Pressable props on native, such as{android_disableSound: true}when the host plays its own sound. HIG keeps the control's name, role, state and press. Blocks with a Close control takeclosePropsthe same way (PositionBlock), typedHeaderCloseProps:ScreenHeaderControlPropsplusdisabled, which draws Close unavailable (webdisabled, no press decoration; native a faint glyph, read as disabled, not pressable), for example while the pane's action is being signed. The sharedHeaderClosecontrol is exported from the same entry. - Hidden title.
hideTitlehides the title visually while it stays the accessible heading, with itsheadingId, so a dialog whose own visible title is drawn elsewhere is not read twice. The header keeps its height and both sides keep their places. - Heading id. On web
headingIdsets theidof theh2, so aDialogor sheet around the pane can name itself witharia-labelledbyand the title is read once. On native it setsnativeIDon the title, foraccessibilityLabelledBy(Android). Without it the heading has no id. - Title ref (native).
titleRefreaches the heading's accessible element (the title, or the title and badge together), so the host can move accessibility focus to it when the pane opens, for example withAccessibilityInfo.setAccessibilityFocus(findNodeHandle(ref.current)). - Test IDs (native).
testIDprefixes<testID>-header,<testID>-backand<testID>-title; without it the header sets none.SettingHeader, the name the settings blocks use inside HIG, is the same component. - Targets. On native the Back control and every other header
IconButtonis drawn at 44dp and reaches 48dp on every side throughhitSlop.
Pinned headers
stickyHeader is one behaviour shared by ScreenHeader and every block that draws it with the prop: PositionBlock, TargetBlock, RewardBlock, SoundHapticsBlock, SignalsBlock, NotificationsBlock, TradeHistoryListBlock, TradeHistoryDetailBlock and, from 0.8.0, ProfileBlock (its top bar with the address and Close controls), ManagePositionBlock, AccountBlock, TokenActionBlock and LanguageBlock. The header stays at the top while the content scrolls, and it is transparent at rest, so whatever the host draws behind the title, such as a sheet's glow, shows through. It takes its fill only once content has scrolled under it. It does not move when it starts to stick, whatever padding the host puts around the block.
-
No jump (web, 0.8.0). Browsers pin a sticky header inside the scroller's own padding, but any padding between the scroller and the block, such as a pane's 12 or 16px inset, used to scroll away first, so the header slid up by that much before it pinned. The script now measures how far a header that leads its pane rests below the scroller's content edge (the top margins, borders and padding of the boxes between them) and pins it there (
--hig-sticky-inset, withdata-sticky-inset), so it pins on the first pixel of scrolling and never moves. Its fill reaches up to the scroller's edge (--hig-sticky-cover, drawn by a::before), so rows do not show through above it, and the fill appears on the script'sdata-scrolledat the moment it pins. A header that follows other content in its pane scrolls up to the edge before it pins, as before. Measured in Chromium and WebKit with a 12px scroller padding and a 16px pane padding:AccountBlock,ProfileBlockandRewardBlockheaders rest at 28px from the scroller's top and stay at 28px at every scroll offset. -
Web. The header is
position: stickyin the nearest scrolling container and fills with--hig-sticky-header-background, which defaults to--hig-background(--hig-screen-backgroundis still read before it). Remap it withvar()to match the scroller, for example--hig-sticky-header-background: var(--hig-overlay)in a sheet. Where the browser has scroll-driven animations, the fill fades in as the header's parent passes the top of the scroller (view-timeline,exit-crossing), with no script. Everywhere, a small script marks the headerdata-scrolledat the same moment, so browsers without them (Firefox) and reduced motion get the same rule, instantly. When the header's parent is itself the scroller (a pane withoverflow: autoaround the header and rows), a view timeline would follow an outer scroller instead, so the script also marks the headerdata-sticky-ownand the scroll-driven fill is left off; the script alone fills it; before the script runs, as in server-rendered markup, the header is transparent. -
Heading ids. Every web block with a header takes
headingId(0.8.0:AccountBlock,TokenActionBlock,LanguageBlock,RewardBlock,SoundHapticsBlock,SignalsBlock,NotificationsBlock, the trade history blocks,SwapBlockwith atitle, andProfileBlock's name heading, besidePositionBlock,TargetBlockandManagePositionBlock), so a hostDialogorGestureSheet(labelledBy) can be named by the block's heading. NativeAccountBlock,TokenActionBlock,LanguageBlock,ProfileBlockandSwapBlockset it as the title'snativeID. -
Native. A block with
stickyHeaderbecomes its own scroll view (scrollComponent, React Native'sScrollViewby default) with the header as its sticky first child; the header is transparent while the scroll offset is at the top and takesstickyHeaderBackground(default the background role; in a sheet passuseColors().overlay) as soon as it moves. Place it in a bounded container such as a sheet body. For a host's own scroller,useStickyHeaderScroll()from the screen-header entry returns{scrolled, onScroll, scrollEventThrottle}: spread the last two on the scroller and passscrolledtoScreenHeaderwithstickyHeader(or toPositionBlockHeader). Give a pinnedScreenHeaderits inset asinset(the blocks' 16), not asstylepadding: React Native moves a sticky child'sstyleonto the slot's own wrapper, outside the fill, whileinsetstays inside it.
// Native: a host pane with a pinned header
const scroll = useStickyHeaderScroll();
<ScrollView stickyHeaderIndices={[0]} onScroll={scroll.onScroll} scrollEventThrottle={scroll.scrollEventThrottle}>
<ScreenHeader title={t.history} onBack={goBack} stickyHeader scrolled={scroll.scrolled} stickyHeaderBackground={colors.overlay} inset={16}/>
{rows}
</ScrollView>Shared host hooks
Two HIGProvider settings reach every block at once. Both are optional and inherited by nested providers; without them nothing a block draws changes.
Press decoration (web). iOS Safari gives a haptic only when the finger lands on a native <input type="checkbox" switch>, so a host that wants that haptic has to put its own element inside each control it presses. pressDecoration={({kind, disabled}) => node} draws the host's node inside these HIG controls: Button, the block action buttons, the swap keypad keys and a ListGroup heading action (kind: 'button', which includes the small capsules such as a help pill), IconButton, the swap flip button and the SearchInput clear button ('icon-button'), a pressable or linked ListRow, a pressable AssetBalanceRow, the WalletAddress copy button, the block rows that open something, the swap token pickers, destination row and receive address ('row'), Switch, a switch ListRow and the settings switch rows ('switch'), each SegmentedControl segment ('segment'), and the header's Back, Close, address and info controls ('back'). disabled is true when the control will not act (disabled or busy), so the host can leave its node out. Checkbox, RadioGroup and Filter do not draw it.
<HIGProvider pressDecoration={({disabled}) => disabled ? null : <HapticSwitch/>}>…</HIGProvider>- Layout. The node sits in one
span.hig-press-decorationthat is the control's last child: absolutely positioned over the whole control (inset: 0), clipped to its radius, out of flow so it adds no gap or size, and withpointer-events: noneon the layer itself while its children take pointer events. A control with no position of its own becomesposition: relativeonly while it holds the layer. The layer'sdata-kindnames the control kind. - Presses. A press on the host's element reaches the control once, with the control's default action. By the HTML rules a click on an interactive element makes that element the activation target, so the control around it would skip its own: a submit or reset
Buttonwould not submit, a linkedListRowwould not navigate, and a switch drawn as a<label>would not toggle. The layer therefore stops that click and sends the control one click of its own (to the switch's input for a switch), carrying the pointer position and modifier keys; a disabled control gets nothing. A host<label for>inside the layer is left to send its own click to its control first, which the layer then forwards. Native click listeners on the control itself see both clicks; React handlers see one. The host keeps its own element out of the accessibility tree and tab order. - Host controls.
PressDecorationfrom@bloxwap/hig/react/providerdraws the same layer inside a host control:<PressDecoration kind='button'/>; passinput(a ref to the switch input) for a host switch drawn as a label. - Native. There is no native equivalent: native haptics are called directly.
Money format. The blocks format dollars with fixed Intl options, so French reads 12,50 $US where a host that uses narrowSymbol reads 12,50 $. numberFormat={{currencyDisplay, useGrouping}} sets how money reads across the provider, on web and native: currencyDisplay is 'symbol', 'narrowSymbol', 'code' or 'name', and useGrouping takes Intl's values, such as 'always' to group a four-digit Spanish amount. It is merged under every currency format HIG draws: the blocks (totals, rows, prices, presets, legends, captions and their spoken labels), BarMark, BarPnl, AssetBalanceRow, the swap pieces, and NumberReadout, Usd and NumberFlow. Options a format sets itself win, so a block's priceOptions or a figure's own options keep their fields. Only style: 'currency' formats change; percentages and plain numbers do not. presentNumberFormat(options, numberFormat) from @bloxwap/hig/contracts returns the same merge for a host-drawn figure.
<HIGProvider locale='fr-FR' numberFormat={{currencyDisplay: 'narrowSymbol'}}>…</HIGProvider>numberFormat.locale is the locale numbers are formatted in when it differs from the interface locale, for example a Korean or Chinese interface whose figures read with US separators: <HIGProvider locale='ko-KR' numberFormat={{locale: 'en-US'}}>. It changes every number HIG formats (separators, digits and the currency's place, money or not), while messages, lang and direction keep the interface locale. useNumberLocale() from either provider entry returns the locale in effect for a host-drawn figure; an empty value is ignored.
Live figures. Every figure a block takes as {value, options, prefix, suffix} (PositionBlock details and rows, ManagePositionBlock action values, RewardBlock details, ProfileBlock row values, BarMark details, SwapBlock captions, destination details and detail rows, and TradeHistoryDetailBlock details) also takes formattedValue: the host's own text for the value, drawn and read in place of Intl's while still moving place by place. Use it where the runtime's Intl does not match the host's number table, for example on Hermes for a locale it formats differently: {value: 1234.5, formattedValue: '1 234,50 $'}. Each digit in the text (ASCII or the locale's own) rolls in its place counted from the end; everything else stays as written. value must still be the number, because it decides the direction of the movement and an unknown value still reads as the dash. Never parse the text back. NumberFlow takes the same pair as formattedValue with animateFormatted; without animateFormatted it keeps host text static, as before.
Native targets. Every block control drawn under the 48dp comfortable target keeps its drawn size and reaches 48dp through hitSlop: the header IconButtons (Back, Close, address, info) and ProfileBlock's round top-bar controls and edit control reach 2dp beyond each 44dp edge, and the 32dp SignalsBlock help pill reaches 8dp beyond each edge.
When to use and examples
Do: compose primitives and explicit outcomes in comfortable app or compact Pro context. Don’t: put wallet/network/SDK services in core packages.
States, interaction and accessibility
Trade confirm remains host-controlled; no demo sends a transaction. Web/native fixtures show market, entry and feedback preference previews.
State review: rest; keyboard focus/hover (DOM); accepted press and release/cancel; selected/checked where applicable; disabled; busy; inline error/recovery; empty/loading; long translations/large text; reduced motion; sound and haptics disabled. No host action occurs on mere focus. Disabled/busy targets suppress accepted activation. Core has no required feedback backend; the optional provider callback follows the action, honors cancellation and isolates errors.
Platform mapping and limits
M2 supplies visual blocks; M3 adds semantic feedback composition because #26 depends on #25. Product visual fidelity is provisional until inaccessible monorepo audit. Account/positions variants can compose these primitives without service coupling.
Validation and citation
See tests/components.dom.test.tsx, tests/pro-data.dom.test.tsx, tests/pro-data-typecheck.tsx, tests/native/components.test.cjs, consumer fixtures and milestone evidence. Physical hardware, assistive-technology and baseline product comparisons are unperformed unless linked explicitly. Cite HIG 0.1.0 with this chapter anchor and a commit permalink, not a mutable preview branch. Preserve business behavior behind a host rollback flag during adoption.