Widget SDK reference

CrossUpload.attach options, modes, methods, events, locales and styling for the browser SDK.

Loading

<script src="https://app.crossupload.com/v1/widget.js"></script>

The SDK is a single versioned file with no third-party dependencies. It defines window.CrossUpload with attach(options), version and locales.

CrossUpload.attach(options)

Enhances exactly one element you choose and returns an uploader instance. Nothing else on the page is modified.

Option	Type	Description
`target`	selector \| Element	Required. In `picker` mode a button or `input[type=file]` whose click opens the modal. In `companion` mode an existing file input; a “Upload from your phone” button is inserted after it.
`mode`	`'picker'` \| `'companion'`	Default `'picker'`. Picker routes local and phone files through CrossUpload. Companion only adds the phone path; the original input keeps working.
`sessionEndpoint`	string	Your backend URL. The SDK sends `POST` with JSON `{ maxFiles, locale, …sessionBody }` and same-origin credentials, and expects the CrossUpload session JSON back.
`sessionHeaders`, `sessionBody`	object	Optional extra headers (for example a CSRF token) and body fields sent to your endpoint.
`fetchSession`	function → Promise	Alternative to `sessionEndpoint`: return the session JSON yourself.
`resultInput`	selector \| Element	Hidden input that receives a JSON array of accepted files: `id`, `sessionId`, `name`, `size`, `mimeType`, `source`. `input` and `change` events fire on it.
`locale`	`'en'` \| `'tr'`	Interface language. Defaults to the browser language when supported.
`maxFiles`	number	A preference forwarded to your endpoint. The server enforces the strictest of plan, project and session limits.
`theme`	`'light'` \| `'dark'` \| `'auto'`	Modal colour scheme. Default `'light'`.
`brandColor`	`'#rrggbb'`	Accent colour for buttons, focus rings and progress.
`companionClass`	string	Extra CSS classes for the inserted companion button (it lives in your DOM, so your styles apply).
`onComplete({ files })`	function	Called when the visitor clicks Done with at least one accepted file.
`onFileReady({ file })`	function	Called each time a file becomes ready (local or phone).
`onChange({ files })`	function	Called whenever the accepted selection changes (including removals).
`onProgress({ file, loaded, total })`	function	Byte-transfer progress for local uploads. Transfer completion is not acceptance.
`onError(error)`	function	`{ code, message, file? }`. See Errors.

Instance methods

open() — open the modal (creates a session lazily if none is active).
close() — close it and restore focus.
destroy() — remove listeners and inserted elements and restore the target’s original attributes.
getFiles() — accepted file results currently selected.
on(name, fn) / off(name, fn) — subscribe to complete, ready, change, progress, error.

DOM events

The target element dispatches bubbling CustomEvents: crossupload:ready, crossupload:change, crossupload:progress, crossupload:complete, crossupload:error. The payload is in event.detail.

File result

{
  "id": "file_opaque_id",
  "sessionId": "ses_opaque_id",
  "name": "document.pdf",
  "size": 248106,
  "mimeType": "application/pdf",
  "source": "phone",            // or "device"
  "status": "ready",
  "url": "https://files.example/…?signature=…",   // temporary
  "urlExpiresAt": "2026-11-03T10:15:00Z",
  "expiresAt": "2026-11-10T10:00:00Z"            // retention deadline
}

The hidden field deliberately excludes url: your server fetches URLs itself.

Behaviour

Never submits your form and never captures other inputs or buttons.
Shadow DOM isolates styles; multiple independent instances work on one page.
Accessibility: focus trap, Escape to close, focus restoration, keyboard-operable controls, live-region announcements, reduced-motion support.
Realtime: a fetch-based SSE client sends the session capability in the Authorization header; on failure it falls back to polling and resumes from the durable event cursor.
Expiry: sessions last ten minutes by default. The modal shows a countdown, “QR code expired. Refresh.” and a “Start again” action.
Phones: when the page is opened on a phone, local selection is shown first, with an option to use another phone.
Removing a file only removes it from the form selection; it does not delete the stored file.

Turkish strings

The tr locale includes “Dosya yükle”, “Bu cihazdan seç”, “Dosyayı buraya sürükle”, “Telefonundan yükle”, “Telefonunun kamerasıyla QR kodu okut.”, “Telefon bağlandı”, “Dosya yükleniyor…”, “Dosya kontrol ediliyor…”, “Dosya eklendi” and “QR kodunun süresi doldu. Yenile.”

Something unclear or wrong? Email [email protected].