TopUpAmountPicker
The card top-up form's body: suggested amounts as a chip radiogroup (one tab stop, arrows move and pick), a custom whole-number amount, the wallet's available money and what it becomes after this top-up, a fee note slot, a payment-method slot, and Cancel / Continue to payment. Enter in the amount submits; an invalid amount is said under the field and nothing is sent.
import { TopUpAmountPicker } from '@ergasti/bricks';Examples
Top up by card
Suggested amounts as buttons, a custom amount checked against min and max, what will be available afterwards, and the submit. topUpAmountError is the check, for your own validation.
Code
import { TopUpAmountPicker, topUpAmountError, useLanguage } from '@ergasti/bricks';
function Amount() {
const language = useLanguage();
return (
<div style={{ maxWidth: 460, display: 'grid', gap: 10 }}>
<TopUpAmountPicker suggested={[5000, 10000, 25000, 50000]} min={1000} max={500000} available="43390.00" defaultValue="10000" onSubmit={() => {}} onCancel={() => {}} />
<small>topUpAmountError for 500: {String(topUpAmountError('500', { min: 1000, max: 500000 }, language))}</small>
</div>
);
}Controlled, with fee and payment method
value and onChange keep the amount in your state (here it shows below); feeNote sits under the figures and paymentMethod above the buttons, both your own nodes.
Code
import { useState } from 'react';
import { SelectBox, TopUpAmountPicker } from '@ergasti/bricks';
function Controlled() {
const [amount, setAmount] = useState('25000');
const [method, setMethod] = useState<'card' | 'wallet'>('card');
return (
<div style={{ maxWidth: 460, display: 'grid', gap: 10 }}>
<TopUpAmountPicker
suggested={[5000, 10000, 25000, 50000]} min={1000} max={500000} available="43390.00"
value={amount} onChange={setAmount}
feeNote="Paid on Paymob. A 2.5% card fee is added on the card page."
paymentMethod={<SelectBox id="topup-method" label="Pay with" value={method} options={[['card', 'Card'], ['wallet', 'Mobile wallet']]} onChange={setMethod} />}
onSubmit={() => {}} onCancel={() => {}}
/>
<small>Amount in your state: {amount || '(empty)'}</small>
</div>
);
}Opening the card page, and a failure
pending locks the picker and says the payment is opening; error shows why the last attempt failed (the server's or the app's sentence).
Code
import { TopUpAmountPicker } from '@ergasti/bricks';
function PendingAndError() {
return (
<div style={{ display: 'grid', gap: 16, gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))' }}>
<TopUpAmountPicker suggested={[5000, 10000]} available="43390.00" defaultValue="10000" pending onSubmit={() => {}} onCancel={() => {}} />
<TopUpAmountPicker suggested={[5000, 10000]} available="43390.00" defaultValue="10000" error="The card page did not open. Try again in a minute." onSubmit={() => {}} onCancel={() => {}} />
</div>
);
}Props
Prop
Type
Labels
Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key topUpAmountPicker, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
amount | Amount ({currency}) | المبلغ ({currency}) |
suggested | Suggested amounts | مبالغ مقترحة |
custom | Or type an amount | أو اكتب المبلغ |
range | From {min} to {max}, whole numbers only. | من {min} لـ {max}، أرقام صحيحة بس. |
availableNow | Available now | المتاح دلوقتي |
availableAfter | Available after this top-up | المتاح بعد الشحنة دي |
submit | Continue to payment | كمّل للدفع |
pending | Opening payment… | بنفتح صفحة الدفع… |
cancel | Cancel | إلغاء |
errEmpty | Pick or type an amount. | اختار أو اكتب المبلغ. |
errWhole | Use a whole number, no decimals. | اكتب رقم صحيح من غير كسور. |
errRange | The amount must be from {min} to {max}. | المبلغ لازم يكون من {min} لـ {max}. |
Design guidance
How the BRICKS design system uses TopUpAmountPicker. Written in docs/content/components/TopUpAmountPicker.md; the props above are read from the code, which wins where the two disagree.
The card top-up form's body: suggested amounts as chips, a whole-number amount field, the wallet's available money and what it becomes, a fee note and Cancel / Continue to payment; use it inside the "Top up by card" modal before sending the brand to the payment provider.
The v3 mock does not draw this form ("Top up by card" only toasts "Opens card top-up (Paymob)"); the library builds it for the real flow. It validates the amount itself (a whole number from min to max, Arabic-Indic digits accepted), shows the error under the field, and calls onSubmit with a number only when valid. The app opens the payment page and later shows the outcome with TopUpResultBanner.
Anatomy
- Fieldset legend (
.kit-blk-topup-l, 13px bold): "Amount (EGP)". - Suggested chips (
.kit-blk-topup-chips,role="radiogroup"): filter chips ("5,000", "10,000"…, tabular, min 88px); the chip matching the typed amount ison. - Amount field (
.kit-blk-topup-f): label "Or type an amount", an LTR numeric text input with the currency word after it, the hint "From 100 to 500,000, whole numbers only." and, when invalid, the error. - Summary (
.kit-blk-sum, soft, radius 16,aria-live="polite"): "Available now" / "Available after this top-up" (aMoneyNoteterm) and the figure in the display face 18px. - Fee note (
.kit-blk-note, 12px muted):feeNote. - Payment method slot:
paymentMethod. - Error (
role="alert"):errorfrom the last attempt. - Actions (end-aligned): Cancel (with
onCancel) and a raspberry submit "Continue to payment" / "Opening payment…".
Variants
| Prop | Look | Use when |
|---|---|---|
suggested non-empty | Chips above the field | The usual form. |
suggested={[]} | Field only | No presets (story NoSuggestions). |
available | Summary box | Show the wallet before and after. |
feeNote / paymentMethod | Extra rows | A "No fee on card top-ups." note; a card/wallet switch. |
value + onChange vs defaultValue | Controlled vs uncontrolled | Controlled when the app needs the amount live. |
States
| State | How | Look |
|---|---|---|
| Default | defaultValue="10000" | 10,000 chip on, summary "Available after this top-up: EGP 53,390.00". |
| Invalid | typed value breaks the rule, or submit with nothing | aria-invalid, message under the field: "Pick or type an amount." / "Use a whole number, no decimals." / "The amount must be from 100 to 500,000."; summary shows "Available now". |
| Pending | pending | Fieldset disabled, aria-busy, submit reads "Opening payment…" and is aria-disabled; Cancel disabled. |
| Payment error | error | Alert line above the actions (story PaymentError). |
| Focus | keyboard | One tab stop for the chips; arrows move and pick; Enter in the field submits. |
Types
Helper: topUpAmountError(value, { min, max }, language, labels?) returns the message or null (same rule, for server-side or custom checks).
TopUpCopy (labels): amount(currency), suggested, custom, range(min, max), availableNow, availableAfter, submit, pending, cancel, errEmpty, errWhole, errRange.
Usage
<Modal open={open} onClose={close} title="Top up by card"
hint="You pay on Paymob. The money lands in your wallet once the payment is confirmed.">
<TopUpAmountPicker
suggested={[5000, 10000, 25000, 50000]}
defaultValue="10000"
min={100}
max={500000}
available={wallet.available} // "43390.00"
feeNote="No fee on card top-ups."
pending={opening}
error={paymobError} // "Paymob did not answer. Try again in a minute."
onCancel={close}
onSubmit={async (amount) => {
setOpening(true);
const { redirectUrl } = await api.startCardTopUp(amount);
window.location.assign(redirectUrl);
}}
/>
</Modal>// Back from Paymob: show the outcome on the Wallet tab
<TopUpResultBanner result={searchParams.get('topup')} onRetry={reopenTopUp} onDismiss={clearParam} />Where it appears
- Brand › Payments › Wallet tab › "Top up" → Top up by card modal (not drawn in the v3 mock; the INVENTORY lists it as built for the real flow).
- Library gallery:
gallery/MissingBrandGallery.tsx("Payments · Top up by card").
Guidelines
Do
- Offer 3–4 suggested amounts that match typical top-ups.
- Pass
availableso the brand sees the wallet after the top-up. - Keep
pendingon until the browser leaves for the payment page. - Show the provider's failure in
errorin plain words.
Don't
- Don't accept decimals; the rule is whole currency units.
- Don't put the currency in the input value; it is drawn beside it.
- Don't disable the submit for an invalid amount: let the press say what is wrong.
RTL and Arabic
- Layout mirrors; the input and chip figures stay LTR.
- Arabic-Indic digits typed ("١٠٠٠٠") are converted before validation.
- Arabic copy: "المبلغ (ج.م)", "أو اكتب المبلغ", "كمّل للدفع", "بنفتح صفحة الدفع…".
Tokens
--ink, --ink-3 (currency, note), --soft (summary), --focus-ring, --font-family-display; field and chip tokens from the kit.
Accessibility
- A real
<form noValidate>;<fieldset>/<legend>group the amount; Enter submits. - Chips:
role="radiogroup"named "Suggested amounts",role="radio"witharia-checked, roving tabindex, arrow keys pick. - Input has a
<label>, the hint and error inaria-describedby,aria-invalidwhen wrong;inputMode="numeric". - Summary is
aria-live="polite", so the new total is announced; the attempt error isrole="alert". - Pending:
aria-busyon the form, submitaria-disabled(stays focusable).
Found in the source
- Roles in the markup:
radiogroup,radio,alert. - ARIA attributes set:
aria-busy,aria-label,aria-checked,aria-invalid,aria-describedby,aria-hidden,aria-live,aria-disabled. - It moves focus in code.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
TopUpResultBanner: the outcome after the payment page.WalletHealthCard: why the brand tops up.BundlePurchaseSummary: the UGC bundle purchase form with a similar summary.
See also: MoneyNote · Button · Money · useBricks · useLanguage · useMoneyDisplay · SelectBox · Card
Source
src/blocks/topup/TopUpAmountPicker.tsx (line 114) on GitHub.