SDK Reference

Complete API documentation for FillKit SDK integration and advanced usage.

New to FillKit? Start with the Quick Start Guide to get up and running in under 5 minutes. This page is a complete reference for all SDK features and configuration options.

Basic Usage

Critical: Initialize FillKit only in development, staging, or test environments—never in production with real users!

Recommended Setup with Environment Check

import { FillKit } from '@fillkit/core';

// Only initialize in non-production environments
const isDev = import.meta.env.DEV;
const isStaging = location.hostname.includes('staging');
const isTest = location.hostname.includes('test');

if (isDev || isStaging || isTest) {
  const fk = new FillKit({
    ui: { enabled: true }  // Auto-inject widgets (default: true)
  });

  console.log('FillKit ready! Press Ctrl+Shift+K to fill forms');
}

Auto-Injected Widgets

When you initialize FillKit with ui.enabled: true (the default), two widgets are automatically injected:

1. Main Widget

A draggable, floating widget positioned at the bottom center (by default) with:

•Fill All Forms button
•Clear All Forms button
•Mode toggle (valid/invalid data)
•Hide/show toggle (Alt+H)
•Drag to reposition anywhere on screen

2. Shortcuts & Settings Panel

Access the shortcuts panel by pressing Ctrl+/ or clicking the shortcuts button in the main widget. The panel displays all keyboard shortcuts and configuration options.

Keyboard Shortcuts

Press Ctrl+/ anytime to see the full shortcuts panel. Most common shortcuts:

Fill all forms on pageCtrl+Shift+K

Fill current/focused formAlt+K

Clear all formsCtrl+Shift+L

Toggle widget visibilityAlt+H

Open shortcuts panelCtrl+/

Toggle valid/invalid modeCtrl+M

Note: On macOS, Ctrl is replaced with Cmd (⌘). All shortcuts are customizable via the SDK configuration.

Configuration Options

mode

'valid' | 'invalid' - Generate valid or invalid data for testing validation

const fk = new FillKit({ mode: 'invalid' }); // Test validation errors

locale

string - Locale for generated data (default: 'en')

const fk = new FillKit({ locale: 'fr' }); // French locale

provider

'local' | 'cloud' - Use local Faker.js or Cloud AI datasets

const fk = new FillKit({
  provider: 'cloud',
  providerConfig: {
    projectId: 'prj_abc123',
    token: 'fk_live_xyz...'
  }
});

Programmatic API (Advanced)

While most users will use the auto-injected widgets and keyboard shortcuts, FillKit also provides a programmatic API for advanced use cases like custom integrations, automation scripts, or building your own UI.

// Fill all forms
await fk.autofillAll({ mode: 'valid' });

// Fill specific form
const form = document.querySelector('#my-form');
await fk.autofill(form);

// Fill currently focused form
await fk.autofillCurrent();

// Clear forms
fk.clear();         // Clear all
fk.clearCurrent();  // Clear current only

// Clean up
fk.destroy();       // Remove widgets and listeners

Events

fk.on('beforeFill', (data) => {
  console.log('About to fill form:', data.form);
});

fk.on('fieldFilled', (data) => {
  console.log(`Filled ${data.semanticType}: ${data.value}`);
});

fk.on('afterFill', (data) => {
  console.log(`Filled ${data.fieldsCount} fields`);
});

fk.on('error', (error) => {
  console.error('Fill error:', error);
});

Quick Start

Cloud Provider