Document Upload Widget

Use the Document Upload Widget to collect important documents (PDF, JPG, PNG) from your end users. This page covers everything from basic usage to handling events and addressing common questions.

Overview

The <niva-document-input> element behaves like a standard HTML <input>:

Dropzone or Click-to-Browse UI: Provides a drag-and-drop area for file selection.

Built-In Validation: Ensures files meet basic validation criteria like file size and file type, but also that it is the correct document type, recently issued, etc.

Minimal Configuration: You only need to provide public-token, submission-token, and any relevant attributes like name.

Embeddable document upload widget

Basic Usage

Here’s the simplest way to place the Document Upload Widget in your HTML. Make sure you’ve completed the steps in Embeddable Widgets: Overview & Installation first (i.e., added the script tag and created a submission on your backend).

User Flow

Empty State

The widget shows a drag-and-drop area or “Browse files” link.

Uploading State

After the user selects a file or drops it in, the widget displays “Uploading…” with a progress indicator.

Success State

When the file is fully uploaded, the widget shows a success message. The component’s “value” now holds the document’s ID.

Success state

Warning State

When the file fails a validation check with a "warning". A warning message is shown to the user, but the file is ultimately accepted.

Warning state

Error State

When the file fails a validation check with a "fail" state, a failure message is displayed. This file is immediately deleted and not accepted.

Error state

When placed within a form, these states also interact with standard HTML validation (if required is specified).

Events & Callbacks

The Niva Document Upload widget emits standard DOM events and supports callback function properties.

Available Events

Event Name	Description	Detail Payload
`widget-initialized`	Fired when the widget is loaded and ready to use	`{ documentType, files }`
`upload-started`	Fired when a file upload begins	`{ file }`
`success`	Fired when a document is successfully uploaded and validated	`{ file }`
`delete-success`	Fired when a document is successfully deleted	`{ file }`
`error`	Fired when any part of the process fails	`{ key, message, file, error? }`

Error Types

The error event includes a key property identifying the specific error type:

Error Key	Description
`invalid_api_key`	Provided API key is invalid
`invalid_token`	Provided submission token is invalid or expired
`initialization_failed`	Initial loading of documents failed
`file_size_too_big`	File exceeds the 50MB size limit
`unsupported_file_type`	File type not supported (only JPG, PNG, PDF allowed)
`upload_error`	Network or server error during upload
`document_incomplete`	Document uploaded but incomplete
`document_validation_failed`	Document rejected by validation
`deletion_failed`	Failed to delete a document

Basic Usage Example

File Object Structure

Event Flow

A typical successful upload follows this sequence: widget-initialized → upload-started → success. If an error occurs at any stage, the error event is fired with the appropriate error key.

Handling Multiple Documents

Each <niva-document-upload> widget accepts a single document type. You must add multiple widgets if you require differnet kinds of documents-one for each document type you require.

Optionally, if you allow multiple documents of the same document type (for example you accept multiple Acta Asamblea documents), you can specify the multiple attribute. The widget will then allow your user to upload multiple of the same document type, and will run validations against each one.

Example:

Accepted Files & Limits

Accepted Types: PDF, PNG, JPG

Maximum File Size: 50MB per file

Document Validation: The widget handles smart instant validation of the document by checking if the correct document type was provided, that it is legible and complete and is associated with the correct business, among others. These validation rules are preconfigured for your account.

Custom Validations

You can pass custom validation data to the widget which can be used to validate the document. Provide this to the component like so:

During normal validations, the name on the document will be matched against the business name in the submission. But when passing a custom name in the validation data, the name on the document must match the custom data ("Juan Pérez" in the example). Use this property to ensure the document is associated with a different entity, like a legal representative or shareholder.

Note: Currently only name-matching validations support custom data. Name-matching is only supported for mx_address_proof, mx_bank_statement, and mx_ine document types.

Component Properties

Attribute	Type	Description
`apiKey`	String	Required. Your public API key, safe to use on the frontend.
`token`	String	Required. The token obtained from your backend after creating a submission with your private token. Expires after 24 hours.
`documentType`	String	Required. This specifies the document type accepted by the widget. Refer to our list of supported document types.
`name`	String	Optional, but strongly recommended. Acts as the name for the form field.
`required`	Boolean	Optional. If present, the widget integrates with standard HTML5 form validation, preventing form submission if no valid file is uploaded.
`disabled`	Boolean	Optional. If present, widget will be disabled.
`multiple`	Boolean	Optional. If present, the widget will accept multiple documents of the same document type.
`locale`	String	Optional. You can pass `"en"` or `"es"` to localize the widget’s built-in texts. Default: `"en"`.
`external_id`	String	Optional. User defined ID for the document

Document Upload Widget

Overview#

Basic Usage#

User Flow#

Events & Callbacks#

Available Events#

Error Types#

Basic Usage Example#

File Object Structure#

Event Flow#

Handling Multiple Documents#

Accepted Files & Limits#

Custom Validations#

Component Properties#