How to import CSV files in Budibase

How to import CSV files in Budibase using CSVBox

Developers building internal tools and B2B SaaS apps with Budibase often need a reliable way to ingest spreadsheets. Budibase doesn’t include a native CSV upload UI, so this guide shows how to add a production-ready CSV import flow in minutes using CSVBox. It’s written for programmers, full-stack engineers, and technical product teams who want a predictable file → map → validate → submit flow (best practices in 2026).

This tutorial covers embedding the CSVBox widget in a Budibase Custom Component, validating and previewing imported rows, and sending parsed data to your Budibase backend or automation endpoints.

Why add CSV import to Budibase?

Budibase is great for building apps quickly, but it lacks a built-in CSV upload UI and schema-driven validation. Common use cases:

Admin panels for bulk customer uploads
CRMs and lead ingestion
SaaS portals that let non-technical users import lists or records

Without a ready-made importer you typically must implement:

Client-side upload UI and progress
CSV parsing and header-to-field mapping
Schema validation and row-level error feedback
Secure submission and server-side ingestion

CSVBox addresses these gaps with a drop-in widget that provides an upload UI, configurable schema enforcement, row-level error messages, and callbacks/webhooks so you can process data where you need it.

Step-by-step: add CSV importing to Budibase

Prerequisites

A deployed Budibase app (cloud or self-hosted)
Familiarity with Budibase Custom Components and internal APIs
A widget created in CSVBox with a defined column schema and credentials

Sign in to CSVBox and create a new widget.
Define your column schema (for example: name, email, phone) and validation rules.
Copy the provided widget credentials: a client_key and widget_hash (or equivalent keys shown in the widget UI).

These identifiers are used to load and authenticate the upload widget inside your Budibase app.

Use Budibase’s Custom Component to inject the widget script and a launch button. Replace the client key, widget hash, and API endpoint to match your setup.

<!-- Load CSVBox SDK -->
<script src="https://js.csvbox.io/0.2/csvbox.js"></script>

<!-- Import button -->
<button id="csvbox-launcher">Import CSV</button>

<script>
  window.addEventListener('load', function () {
    const importer = new CSVBox("YOUR_CLIENT_KEY", {
      widgetHash: "YOUR_WIDGET_HASH",
      user: {
        id: "user_123",
        name: "Alice Doe"
      },
      onData: function (data) {
        // onData receives parsed rows from CSVBox.
        // The payload shape depends on your widget configuration
        // (often an object containing a `data` array of rows).
        console.log("CSVBox Data:", data);

        // Send parsed rows to your Budibase endpoint or external API.
        fetch('https://your-api-endpoint.com/data-import', {
          method: 'POST',
          headers: {'Content-Type': 'application/json'},
          body: JSON.stringify(data)
        }).then(r => {
          if (!r.ok) console.error('Import failed', r.statusText);
        }).catch(err => console.error('Network error', err));
      }
    });

    document.getElementById("csvbox-launcher").addEventListener('click', function () {
      importer.open();
    });
  });
</script>

Notes:

Replace “YOUR_CLIENT_KEY” and “YOUR_WIDGET_HASH” with credentials from CSVBox.
The example uses fetch() to POST the parsed payload. Adjust the URL to point to a Budibase internal API or your automation endpoint.

Step 3 — handle imported data in Budibase

Budibase lets you receive incoming requests with automation or internal endpoints. The example below shows the server-side handler pattern: parse the request body, map fields, and insert into a Budibase collection/table.

// POST /data-import
exports.handler = async function (event) {
  const body = JSON.parse(event.body);

  // CSVBox payloads commonly include an array of rows (e.g., body.data).
  // Adjust the path below to match the actual payload shape from your widget.
  const rows = body.data || body;

  for (const row of rows) {
    await budibase.db.insert('contacts', {
      name: row.name,
      email: row.email,
      phone: row.phone
    });
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ success: true })
  };
};

Checklist:

Ensure your Budibase app has a ‘contacts’ collection (or modify the table name).
Confirm field mappings (row.name, row.email) match your CSV column names or mapped headers.

Key integration elements

Import button

Widget initialization new CSVBox(“client_key”, { widgetHash: “widget_hash”, onData: function (data) { // handle data } });

client_key and widget_hash identify your widget
onData() runs after a successful import and receives parsed rows (inspect the payload in your console to confirm shape)

Data submission example fetch(‘/data-import’, { method: ‘POST’, headers: {‘Content-Type’: ‘application/json’}, body: JSON.stringify(data) });

This example sends imported data to a Budibase backend endpoint or external API for storage and further processing.

Troubleshooting: common issues

CSV upload modal not appearing?

Confirm the CSVBox CDN script is included and accessible.
Check the browser console for errors and network requests.

Data not received at the server?

Log the payload inside onData() to inspect the parsed structure.
Verify the widget schema matches the uploaded file headers and mappings.
Confirm your server endpoint URL is reachable and accepts POST requests.

CORS or HTTP errors?

For external endpoints, ensure CORS is configured correctly.
Use a Budibase internal automation endpoint during development to avoid cross-origin restrictions.

Row-level validation or mapping issues?

Adjust your CSVBox widget schema to enforce required fields, types, and constraints.
Use CSVBox’s preview and row-error UI so users can fix issues before submission.

Why use CSVBox for Budibase CSV uploads?

CSVBox simplifies the file → map → validate → submit flow with features that reduce backend work and end-user friction:

Intuitive upload UI with drag-and-drop and progress feedback
Schema enforcement (required fields, types, allowed values)
Row-level error messaging so users fix issues before import
JavaScript callbacks and webhooks for flexible server-side processing
Auditability and import history (where provided by the CSVBox dashboard)

Using CSVBox avoids reinventing CSV parsing, header mapping, and row validation logic — letting teams ship import workflows faster and with fewer bugs.

Summary — add powerful CSV upload to Budibase in minutes (as of 2026)

To add CSV upload to Budibase:

Configure a schema-based widget in CSVBox.
Embed the widget script and a launch button inside a Budibase Custom Component.
Capture parsed rows in onData() and forward them to internal APIs or automation endpoints for storage.

This produces a clear file → map → validate → submit workflow that reduces support overhead and speeds up data onboarding for admin panels, CRMs, and SaaS portals.

📘 Learn more in the CSVBox integration docs: https://help.csvbox.io/getting-started/2.-install-code

—

Get started at https://www.csvbox.io and add spreadsheet import to your Budibase app with minimal code.

How to import CSV files in Budibase