UI/UX Best Practices

The Document Upload Widget provides a minimal user interface for file selection, including drag-and-drop functionality, progress tracking, and success/error messaging. However, it does not display headings, labels, or any contextual instructions about what document is needed.

Your responsibility is to build the surrounding UI so users understand why they are uploading a file, what to upload, and how to do it properly. This page covers best practices for placing and labeling the widget in your application.

Recommendations

Provide Clear Headings and Explanations

Give Each Document a Title: For example, “Constancia de situación fiscal” or “Carátula bancaria.”

Explain What It Is: Provide a brief description of the document itself—what information it typically includes or its official purpose (e.g., “A Constancia de situación fiscal is an official certificate that lists your company’s tax registration details.”). This helps users verify they’re uploading the correct file.

Explain Why It’s Needed: A short sentence can clarify how it will be used or what the user should expect.

Summarize Key File Requirements

Highlight Allowed Formats: Mention “PDF, JPG, or PNG only” and any size limits (e.g., 50MB max).

Specify Content or Date Constraints: If a document must be recent or include certain information, say so explicitly. For example, a proof of address must be issued within the last 90 days or that a tax status certificate must show the tax status as active.

Logical Flow: Introduce the document requirements in text, then place <niva-document-upload> right underneath.

Minimize Confusion: This helps users see instructions and the upload area together.

Single-Document Type Limit: Each widget handles just one document type.

Multiple Documents: If you need three documents, include three separate instances of <niva-document-upload>—each with its own heading and explanation.

Keep the Layout Manageable

Avoid Overloading: If you require many documents, consider using a multi-step form or displaying them in separate sections.

Mobile Friendliness: Ensure there’s enough space for users to tap or drag files easily on smaller screens. The widget will expand to fill the full width available to it.

Plan for Error Handling

Token Expiration: If the submission token expires during upload, the widget shows an error. Guide users to refresh the page or restart the process, or handle the token refresh behind the scenes.

Upload Failures: Tell users what to do if their file is required, but not uploaded, or if there is a connection failure.

Example Layout

In this example, each document requirement is labeled (“Constancia de situación fiscal,” “Carátula bancaria,” etc.), with a brief description of what the file should contain and the <niva-document-upload> widget placed directly underneath.

UI/UX Best Practices

Recommendations

Provide Clear Headings and Explanations

Summarize Key File Requirements

Place the Widget Immediately Below Its Description

Use One Widget per Required Document

Keep the Layout Manageable

Plan for Error Handling

Example Layout

UI/UX Best Practices

Recommendations#

Provide Clear Headings and Explanations#

Summarize Key File Requirements#

Place the Widget Immediately Below Its Description#

Use One Widget per Required Document#

Keep the Layout Manageable#

Plan for Error Handling#

Example Layout#

Recommendations

Provide Clear Headings and Explanations

Summarize Key File Requirements

Place the Widget Immediately Below Its Description

Use One Widget per Required Document

Keep the Layout Manageable

Plan for Error Handling

Example Layout