ReceiptUpload
A payout's transfer receipt (the PR admin's affiliate.payouts.receipt): a drop zone with a real file input behind a "choose a file" button; the type (PDF, JPG, PNG) and size are checked before onSelect, so a wrong file is explained at once. Then the upload progress, the uploaded file (thumbnail or PDF icon, name, size, View / Replace / Remove), or the error with a retry. Presentational: the app uploads and passes the state back. A file needs an allowed MIME type and a matching extension, and nothing is taken while one uploads; the server must still re-check every upload (see onSelect).
import { ReceiptUpload } from '@ergasti/bricks';Examples
Receipt upload
Four states: empty (a drop area and a button), uploading (with progress), uploaded (file name, size, View and Remove) and error. The component only reports the chosen File; you upload it and set the state.
Code
import { useState } from 'react';
import { ReceiptUpload, fileSize, type ReceiptState } from '@ergasti/bricks';
function Upload() {
const [state, setState] = useState<ReceiptState>('empty');
return (
<div style={{ maxWidth: 440 }}>
<ReceiptUpload state={state} progress={64} file={{ name: 'instapay-4471.pdf', size: 1_250_000, kind: 'pdf' }} onSelect={() => setState('uploaded')} onView={() => {}} onRemove={() => setState('empty')} />
<small>File size helper: {fileSize(1_250_000, 'en')}</small>
</div>
);
}All states side by side
Code
import { ReceiptUpload } from '@ergasti/bricks';
function States() {
return (
<div style={{ display: 'grid', gap: 14, maxWidth: 440 }}>
<ReceiptUpload state="uploading" progress={64} onSelect={() => {}} />
<ReceiptUpload state="error" error="The file is larger than 5 MB." onSelect={() => {}} />
<ReceiptUpload state="empty" disabled onSelect={() => {}} />
</div>
);
}A smaller limit
maxBytes sets the size check before upload (default 5 MB); here 1 MB, so most phone photos are refused with a message.
Code
import { useState } from 'react';
import { ReceiptUpload } from '@ergasti/bricks';
function SmallLimit() {
const [error, setError] = useState<string | undefined>();
return (
<div style={{ maxWidth: 440 }}>
<ReceiptUpload state={error ? 'error' : 'empty'} error={error} maxBytes={1024 * 1024} onSelect={(f) => setError(`Picked ${f.name}; your app uploads it now.`)} />
</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 prReceiptUpload, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
label | Transfer receipt | إيصال التحويل |
drop | Drop the receipt here or | اسحب الإيصال هنا أو |
choose | choose a file | اختار ملف |
types | PDF, JPG or PNG · up to {mb} MB | PDF أو JPG أو PNG · لحد {mb} ميجا |
uploading | Uploading… {p}% | بنرفع… {p}% |
uploaded | Receipt uploaded | الإيصال اترفع |
view | View | شوف |
replace | Replace | غيّره |
remove | Remove | امسحه |
retry | Choose again | اختار تاني |
badType | Use a PDF, JPG or PNG file. | استخدم ملف PDF أو JPG أو PNG. |
tooBig | The file is over {mb} MB. | الملف أكبر من {mb} ميجا. |
mb | {v} MB | {v} ميجا |
kb | {v} KB | {v} كيلو |
proof | The creator sees this receipt as proof of payment. | صانع المحتوى بيشوف الإيصال ده كإثبات إن الفلوس اتدفعت. |
Design guidance
How the BRICKS design system uses ReceiptUpload. Written in docs/content/components/ReceiptUpload.md; the props above are read from the code, which wins where the two disagree.
A drop zone for a payout's transfer receipt with type and size checks, upload progress, the uploaded file and errors; use it in the PR Portal's payout drawer or modal when PR attaches proof of payment.
ReceiptUpload follows the PR admin's affiliate.payouts.receipt: PR drops or picks a PDF, JPG or PNG; the component checks the type (MIME type and matching extension) and the size before calling onSelect, so a wrong file is explained at once. The app uploads and moves state through uploading → uploaded (or error). It is presentational: it holds no file and calls no server. Payouts are not drawn in the v3 mock; this block is inferred from the PR admin domain.
Anatomy
- Label: "Transfer receipt" (13px / 700), which also names the hidden file input.
- Drop zone (
empty,uploading,error): dashed 1.5px border,--softfill, radius--radius-lg, centred; a 40px white upload icon tile; "Drop the receipt here or choose a file" (a raspberry link button); a muted types line "PDF, JPG or PNG · up to 5 MB". - Progress (
uploading): "Uploading… 64%" over a 6px olive track (role="progressbar"). - File row (
uploaded): 52px thumbnail (image) or raspberry PDF tile, the file name (one line,dir="auto"), "✓ Receipt uploaded · 1.2 MB", then View / Replace / Remove small buttons. - Error: a
role="alert"line under the zone. - Hint: "The creator sees this receipt as proof of payment."
Variants
No visual variant props; the look follows state.
States
| State | Trigger | Look |
|---|---|---|
| Empty | state="empty" | Drop zone, "choose a file" |
| Drag over | a file dragged over the zone | Raspberry border, raspberry tint |
| Uploading | state="uploading", progress 0-100 | Progress line and bar; drops and picks ignored |
| Uploaded | state="uploaded" and file | File row with View (with onView), Replace, Remove (with onRemove) |
| Error | state="error", error | Red border, alert text, link reads "Choose again" |
| Local check failed | wrong type or over maxBytes | "Use a PDF, JPG or PNG file." / "The file is over 5 MB." (no onSelect) |
| Disabled | disabled | Zone at 55% opacity, link disabled; Replace and Remove hidden |
| Long file name | any | One line with ellipsis |
Types
Also exported: fileSize(bytes, language) ("1.2 MB" / "340 KB"). Words: provider labels.prReceiptUpload.
ReceiptState (state): 'empty' | 'uploading' | 'uploaded' | 'error'. ReceiptFile (file): { name, size (bytes), kind: 'image' | 'pdf', previewUrl? }, shown when uploaded.
Usage
import { ReceiptUpload } from '@ergasti/bricks';
<ReceiptUpload
state={upload.state}
progress={upload.progress}
file={upload.file}
error={upload.error}
onSelect={(file) => startUpload(payout.id, file)}
onView={() => window.open(upload.file!.previewUrl ?? receiptUrl)}
onRemove={() => removeReceipt(payout.id)}
/>// Payouts: the receipt column opens a modal with the upload
<DataTable label="Payouts" rows={payouts} columns={payoutColumns('en', { onReceipt: setReceiptFor })} rowKey={(p) => p.id} />
<Modal open={receiptFor != null} onClose={() => setReceiptFor(null)} title="Receipt for Nour Hassan · EGP 5,200">
<ReceiptUpload state="uploaded" file={{ name: 'instapay-4471.pdf', size: 1_250_000, kind: 'pdf' }} onSelect={replace} onView={view} />
</Modal>Receipt upload. Four states: empty (a drop area and a button), uploading (with progress), uploaded (file name, size, View and Remove) and error. The component only reports the chosen File; you upload it and set the state. (docs example Upload)
import { useState } from 'react';
import { ReceiptUpload, fileSize, type ReceiptState } from '@ergasti/bricks';
export function Upload() {
const [state, setState] = useState<ReceiptState>('empty');
return (
<div style={{ maxWidth: 440 }}>
<ReceiptUpload state={state} progress={64} file={{ name: 'instapay-4471.pdf', size: 1_250_000, kind: 'pdf' }} onSelect={() => setState('uploaded')} onView={() => {}} onRemove={() => setState('empty')} />
<small>File size helper: {fileSize(1_250_000, 'en')}</small>
</div>
);
}Where it appears
- Library-only (no v3 mock screen): Payouts and receipts › receipt modal or drawer, paired with
PrStatusPillreceipt_missing/receipt_uploadedin the payouts table.
Guidelines
Do
- Re-validate on the server: the browser's MIME type and name are not a security boundary.
- Pass the server's message in
errorand keepstate="error"until PR picks again. - Show a thumbnail (
previewUrl) for image receipts so PR can confirm the right file.
Don't
- Don't start a second upload while one runs (the component ignores it; don't work around it).
- Don't raise
maxByteswithout telling PR in the copy (the types line uses it). - Don't use it for gift photos or other uploads: its copy is about transfer receipts.
RTL and Arabic
The layout mirrors; the file name uses dir="auto" and the size is dir="ltr" so "1.2 ميجا" reads correctly. Arabic words: "إيصال التحويل", "اسحب الإيصال هنا أو اختار ملف", "بنرفع… 64%", "الإيصال اترفع".
Tokens
--color-control-border-hover, --radius-lg, --radius-md, --soft, --rasp, --rasp-50, --rasp-d, --bad, --card, --ink-2, --line, --ok, --track, --olive.
Accessibility
- A real
<input type="file">(hidden) labelled by "Transfer receipt", opened by a real button; drag and drop is an extra, not the only way. - The button is described by the types line (
aria-describedby). - Uploading: the zone is
aria-busy; the bar isrole="progressbar"witharia-valuenow, labelled by the label. - Errors are
role="alert". The thumbnail is decorative (alt=""); the file name is text. - Touch (≤1024px): the link gets a 44px hit area.
Found in the source
- Roles in the markup:
progressbar,alert. - ARIA attributes set:
aria-labelledby,aria-hidden,aria-busy,aria-valuemin,aria-valuemax,aria-valuenow,aria-describedby.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
PrStatusPill(receipt_missing,receipt_uploaded): the receipt's status in the table.payoutColumns: the payouts table preset with its receipt action.Modal(kit): the frame the upload usually sits in.
See also: Button · PrIcon · useLanguage · BulkAction · ChangePreview · ChoiceGroup · DecisionsCard
Source
src/pr/ReceiptUpload.tsx (line 81) on GitHub.