Skip to Content
BBRICKSv0.7.4
PR PortalForms and dialogs

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.

prReceiptUpload
KeyEnglishArabic
labelTransfer receiptإيصال التحويل
dropDrop the receipt here orاسحب الإيصال هنا أو
choosechoose a fileاختار ملف
typesPDF, JPG or PNG · up to {mb} MBPDF أو JPG أو PNG · لحد {mb} ميجا
uploadingUploading… {p}%بنرفع… {p}%
uploadedReceipt uploadedالإيصال اترفع
viewViewشوف
replaceReplaceغيّره
removeRemoveامسحه
retryChoose againاختار تاني
badTypeUse a PDF, JPG or PNG file.استخدم ملف PDF أو JPG أو PNG.
tooBigThe file is over {mb} MB.الملف أكبر من {mb} ميجا.
mb{v} MB{v} ميجا
kb{v} KB{v} كيلو
proofThe 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

  1. Label: "Transfer receipt" (13px / 700), which also names the hidden file input.
  2. Drop zone (empty, uploading, error): dashed 1.5px border, --soft fill, 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".
  3. Progress (uploading): "Uploading… 64%" over a 6px olive track (role="progressbar").
  4. 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.
  5. Error: a role="alert" line under the zone.
  6. Hint: "The creator sees this receipt as proof of payment."

Variants

No visual variant props; the look follows state.

States

StateTriggerLook
Emptystate="empty"Drop zone, "choose a file"
Drag overa file dragged over the zoneRaspberry border, raspberry tint
Uploadingstate="uploading", progress 0-100Progress line and bar; drops and picks ignored
Uploadedstate="uploaded" and fileFile row with View (with onView), Replace, Remove (with onRemove)
Errorstate="error", errorRed border, alert text, link reads "Choose again"
Local check failedwrong type or over maxBytes"Use a PDF, JPG or PNG file." / "The file is over 5 MB." (no onSelect)
DisableddisabledZone at 55% opacity, link disabled; Replace and Remove hidden
Long file nameanyOne 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 PrStatusPill receipt_missing / receipt_uploaded in 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 error and keep state="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 maxBytes without 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 is role="progressbar" with aria-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.

  • 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.

On this page