Widget

The KVKBase widget adds instant company lookup auto-complete to any HTML form. Just add a single script tag -- no framework required.

Quick Start

Add the widget script to your page, pointing it at your KVK input field:

html
<script
  src="https://widget.kvkbase.nl/v1/widget.js"
  data-apikey="YOUR_API_KEY"
  data-target="#kvk-input"
  data-autofill="true"
></script>

That is all you need. The widget will attach to your input field, show a dropdown as the user types, and auto-fill related fields when a company is selected.

Token usage The widget uses the /v1/autocomplete endpoint (1 token per search) and /v1/lookup (1 token) when a company is selected.

Configuration

Configure the widget using data- attributes on the script tag.

Required attributes

Attribute Description
data-apikey Your KVKBase API key
data-target CSS selector for the KVK input field (e.g. #kvk-input)

Auto-fill targets

When data-autofill="true", the widget fills related form fields automatically. Specify each field with a CSS selector:

Attribute Default Description
data-autofill false Enable auto-fill of related fields
data-name-target -- Selector for company name field
data-address-target -- Selector for address field
data-city-target -- Selector for city field
data-postal-target -- Selector for postal code field
data-vat-target -- Selector for VAT number field

Display options

Attribute Default Description
data-theme light Widget theme: light or dark
data-lang nl Language: nl or en

CSS Customization

Override the widget appearance using CSS custom properties. Set them on :root or on a parent element:

css
:root {
  --kvkbase-primary: #2563eb;
  --kvkbase-bg: #ffffff;
  --kvkbase-text: #0f172a;
  --kvkbase-border: #e2e8f0;
  --kvkbase-radius: 8px;
  --kvkbase-font: "Inter", sans-serif;
  --kvkbase-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
  --kvkbase-item-hover-bg: #f8fafc;
  --kvkbase-max-height: 300px;
}

Available CSS properties

Property Default Description
--kvkbase-primary #2563eb Highlight color for selected items and focus states
--kvkbase-bg #ffffff Dropdown background color
--kvkbase-text #0f172a Text color in dropdown items
--kvkbase-border #e2e8f0 Border color for the dropdown
--kvkbase-radius 8px Border radius for the dropdown container
--kvkbase-font System font Font family for dropdown text
--kvkbase-shadow Subtle shadow Box shadow for the dropdown
--kvkbase-item-hover-bg #f8fafc Background color for hovered items
--kvkbase-max-height 300px Maximum height of the dropdown (scrolls if exceeded)

Events

The widget dispatches custom events on the target element. Use these to react to user actions.

kvkbase:found

Fired when a company is successfully selected from the dropdown. The event.detail contains the full company object.

javascript
document.querySelector("#kvk-input").addEventListener("kvkbase:found", (e) => {
  console.log("Company found:", e.detail);
  // e.detail contains:
  // {
  //   kvkNumber: "12345678",
  //   name: "Acme B.V.",
  //   address: { street, houseNumber, postalCode, city },
  //   vatNumber: "NL123456789B01",
  //   vatValid: true
  // }
});

kvkbase:error

Fired when a lookup fails (network error, invalid KVK number, rate limit exceeded, etc.).

javascript
document.querySelector("#kvk-input").addEventListener("kvkbase:error", (e) => {
  console.error("Lookup failed:", e.detail.message);
  // e.detail: { code: "NOT_FOUND", message: "..." }
});

Full Working Example

A complete HTML form with the widget and auto-fill, ready to copy-paste:

html
<!DOCTYPE html>
<html lang="nl">
<head>
  <meta charset="utf-8">
  <title>Checkout</title>
</head>
<body>
  <form>
    <label>KVK Nummer</label>
    <input type="text" id="kvk-input" placeholder="12345678">

    <label>Bedrijfsnaam</label>
    <input type="text" id="company-name" readonly>

    <label>Adres</label>
    <input type="text" id="address" readonly>

    <label>Stad</label>
    <input type="text" id="city" readonly>

    <label>Postcode</label>
    <input type="text" id="postal" readonly>

    <label>BTW Nummer</label>
    <input type="text" id="vat" readonly>
  </form>

  <script
    src="https://widget.kvkbase.nl/v1/widget.js"
    data-apikey="YOUR_API_KEY"
    data-target="#kvk-input"
    data-autofill="true"
    data-name-target="#company-name"
    data-address-target="#address"
    data-city-target="#city"
    data-postal-target="#postal"
    data-vat-target="#vat"
  ></script>

  <script>
    // Listen for events
    document.querySelector("#kvk-input")
      .addEventListener("kvkbase:found", (e) => {
        console.log("Selected:", e.detail.name);
      });
  </script>
</body>
</html>