Embeddable Widget

Add image conversion to your website with a single script tag.

Quick Start

Add this script tag anywhere in your HTML. The widget renders immediately after the tag:

<script src="http://localhost:8000/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-mode="all"
        data-theme="auto"></script>

That's it! The widget creates its own container and starts working.

Configuration Options

Configure the widget via data-* attributes on the script tag or options passed to KoalaPic.init():

Option	Data Attribute	Default	Description
`mode`	`data-mode`	`"all"`	Widget mode: `convert`, `compress`, `resize`, or `all`
`theme`	`data-theme`	`"auto"`	Color theme: `light`, `dark`, or `auto` (follows system)
`accent_color`	`data-accent-color`	`"#3b82f6"`	Primary accent color (hex). Example: `#8b5cf6`
`allowed_formats`	`data-allowed-formats`	`(all)`	Comma-separated output formats: avif, bmp, gif, heic, ico, jpg, pdf, png, svg, tiff, webp
`max_file_size`	`data-max-file-size`	`50`	Maximum upload size in MB (1–50)
`callback_url`	`data-callback-url`	`(none)`	URL to POST conversion results to on completion
`hide_branding`	`data-hide-branding`	`false`	Hide "Powered by KoalaPic" footer
`api_key`	`data-api-key`	`(none)`	API key for authenticated requests with higher rate limits
`width`	`data-width`	`"100%"`	Widget iframe width (any CSS value)
`height`	`data-height`	`"500px"`	Widget iframe height (auto-adjusts via resize events)
`lang`	`data-lang`	`(auto)`	Language code (e.g. `fr`, `de`, `ar`). Auto-detected from page or browser if omitted.

All options support both snake_case and camelCase in the JavaScript API (e.g. accent_color or accentColor).

JavaScript API

For full control, use KoalaPic.init() to create widgets programmatically:

<div id="converter"></div>
<script src="http://localhost:8000/static/widget/koalapic-widget.js"></script>
<script>
  var iframe = KoalaPic.init('#converter', {
    mode: 'convert',
    theme: 'dark',
    accentColor: '#8b5cf6',
    allowedFormats: ['jpg', 'png', 'webp'],
    maxFileSize: 25,
    apiKey: 'kp_your_key_here'
  });
</script>

API Reference

Method	Description
`KoalaPic.init(selector, config)`	Create a widget inside a container element. Returns the iframe element. Accepts a CSS selector string or DOM element.
`KoalaPic.on(event, callback)`	Register an event listener. Events
`KoalaPic.version`	Library version string.

Event Handling

Listen for conversion lifecycle events using KoalaPic.on():

KoalaPic.on('conversion_completed', function(result) {
  console.log('Conversion ID:', result.id);
  console.log('Download token:', result.download_token);
  console.log('Format:', result.output_format);
  console.log('File size:', result.file_size);
});

KoalaPic.on('conversion_started', function(data) {
  console.log('Conversion started in mode:', data.mode);
});

KoalaPic.on('conversion_failed', function(data) {
  console.error('Conversion failed:', data.error);
});

Event Types

Event	Payload	Description
`conversion_started`	`{ mode }`	Conversion submitted to the API
`conversion_completed`	`{ id, download_token, output_format, file_size }`	Conversion finished successfully
`conversion_failed`	`{ error }`	Conversion or API request failed

You can also listen to raw postMessage events directly:

window.addEventListener('message', function(event) {
  if (event.data.type === 'koalapic:conversion_complete') {
    console.log(event.data.payload);
  }
});

Callback URL

Set callback_url to automatically POST conversion results to your server:

<script src="http://localhost:8000/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-callback-url="https://yoursite.com/api/conversion-hook"></script>

Your endpoint receives a JSON POST with the conversion result:

{
  "id": "abc123",
  "download_token": "token_xyz",
  "output_format": "webp",
  "file_size": 45210
}

Styling & Customization

The widget renders inside an iframe, so it won't conflict with your page styles. You can customize the container:

<!-- Fixed-width centered widget -->
<div id="widget" style="max-width: 600px; margin: 0 auto;"></div>
<script src="http://localhost:8000/static/widget/koalapic-widget.js"></script>
<script>
  KoalaPic.init('#widget', {
    width: '100%',
    height: '500px',
    accentColor: '#e11d48',
    theme: 'dark'
  });
</script>

The iframe has border-radius: 8px by default. Override it on the returned iframe element:

var iframe = KoalaPic.init('#widget', { mode: 'compress' });
iframe.style.borderRadius = '16px';
iframe.style.boxShadow = '0 4px 24px rgba(0,0,0,0.1)';

Rate Limiting

For production use, we recommend passing an API key via the data-api-key attribute. Anonymous requests are limited to 10 conversions per minute. Authenticated requests get 30 per minute.

Get your free API key at http://localhost:8000/dashboard/keys/

Examples

Compress-only widget

<script src="http://localhost:8000/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-mode="compress"
        data-theme="light"
        data-accent-color="#10b981"></script>

Resize-only with limited formats

<script src="http://localhost:8000/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-mode="resize"
        data-allowed-formats="jpg,png,webp"
        data-max-file-size="10"></script>

Multiple widgets on one page

<div id="converter-1"></div>
<div id="converter-2"></div>
<script src="http://localhost:8000/static/widget/koalapic-widget.js"></script>
<script>
  KoalaPic.init('#converter-1', { mode: 'convert' });
  KoalaPic.init('#converter-2', { mode: 'compress' });
</script>

Live Preview

Here's the widget in action: