Developer Documentation

Overview & Benefits#

The Add-to-List integration is designed to be lightweight and easy to embed. You can use it in two main ways, depending on your use case:

• Custom Button – Ideal for predefined item lists. You have full control over which items are added.
• Automatic Button – Automatically extracts items from your HTML structure. Perfect for recipe blogs and structured content.

Both methods use a simple JavaScript snippet and hosted scripts provided by Listonic. You can start with the Custom Button for maximum control, or the Automatic Button to automatically convert existing ingredient lists into Add-to-List buttons.

Custom Add-to-List Button#

The Custom Button gives you full control over which items are added to the user's shopping list. You define the items directly in JavaScript, and the button triggers adding them to Listonic.

When to Use

• You have a predefined list of items (e.g., product bundles, meal kits)
• You want complete control over the item list
• Your items are generated dynamically via JavaScript
• You're building an e-commerce integration

Script URL

https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js

Basic Implementation

<script type="text/javascript">
  // Items to be added – HTML supported
  listonic_content = 'item <a href="http://example.com">one</a><br/>item two<br/>';

  // Optional: alternative button text ("Add to shopping list")
  listonic_alternateText = 'true';

  // Optional: default list name
  listonic_name = 'My shopping list';

  // Required container for the button
  document.write("<iframe class='listonic_ifrm' frameborder='0' scrolling='no'></iframe>");
</script>
<script type="text/javascript"
        src="https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js">
</script>

Automatic Button#

The Automatic Button is designed for structured content such as recipes and food blogs. It automatically reads ingredients from your HTML and exposes an Add-to-List experience without requiring you to manually define the items in JavaScript.

When to Use

• You have recipe pages with ingredient lists in HTML
• You want automatic extraction without manual configuration
• Your content follows a consistent HTML structure
• You're running a food blog or recipe website

Script URL

https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/blogwidget.js

Basic Implementation

<!-- Ingredient list on your page -->
<div class="recipe__wrapper__list">
  <ul>
    <li>1 onion</li>
    <li>2 tomatoes</li>
    <li>Olive oil</li>
  </ul>
</div>

<script type="text/javascript">
  // Widget mode
  var listonic_bw_type = "generic";

  // Class or ID of the HTML element containing ingredients
  var listonic_bw_generic_entryClass = "recipe__wrapper__list";

  // Optional: hide the sidebar and use a more compact mode
  var listonic_hideSideBar = true;
</script>
<script src="https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/blogwidget.js"
        charset="UTF-8"></script>

How Automatic Extraction Works

The widget scans the HTML element specified by listonic_bw_generic_entryClass and extracts text content from list items (<li>) or other text nodes. Each item becomes an entry in the shopping list.

Multiple Buttons on One Page#

If you need multiple Add-to-List buttons on the same page, use indexed variable names. Each button uses its own content and list name.

<script type="text/javascript">
  // First button
  listonic_content_0 = 'Milk<br/>Eggs<br/>';
  listonic_name_0 = 'Breakfast';
  document.write("<iframe class='listonic_ifrm' frameborder='0' scrolling='no' id='listonic_ifrm_0'></iframe>");
</script>
<script type="text/javascript"
        src="https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js">
</script>

<!-- Second button -->
<script type="text/javascript">
  listonic_content_1 = 'Chicken<br/>Rice<br/>Vegetables';
  listonic_name_1 = 'Dinner';
  document.write("<iframe class='listonic_ifrm' frameborder='0' scrolling='no' id='listonic_ifrm_1'></iframe>");
</script>
<script type="text/javascript"
        src="https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js">
</script>

Custom Button Parameters#

Automatic Button Parameters#

Button Styling#

By default, the Listonic button uses standard styling. If you want to better match your site's look and feel, you can override selected colors inside the embedded iframe.

Custom Colors#

The following snippet updates all Listonic button iframes on the page with custom colors:

<script type="text/javascript">
  setTimeout(function () {
    var iconColor = '#54AB26';       // Icon fill color
    var iconBackground = '#eeeeee'; // Icon background
    var textBackground = '#eeeeee'; // Button background
    var textColor = '#747474';       // Text color

    var frames = document.getElementsByClassName("listonic_ifrm_used");
    for (var i = 0; i < frames.length; i++) {
      var cssStyle = document.createElement("style");
      var css =
        '.listonic-button { background-color: ' + textBackground + ';}' +
        '.listonic-button-icon svg {fill: ' + iconColor + ';}' +
        '.listonic-button-icon { background-color: ' + iconBackground + ';}' +
        '.listonic-button-text svg {fill: ' + textColor + ';}';
      cssStyle.type = 'text/css';
      cssStyle.appendChild(document.createTextNode(css));
      frames[i].contentDocument.head.appendChild(cssStyle);
    }
  }, 0);
</script>

Available CSS Classes

Dynamic Content (AJAX/SPAs)#

If you inject content dynamically (for example, via AJAX or a frontend framework), ensure the Listonic scripts run after the content is present in the DOM.

// Track script loading and button instances
var listonicScriptLoaded = false;
var listonicButtonIndex = 0;

// After your content is loaded via AJAX
function initListonicButton(items, listName, containerId) {
  var container = document.getElementById(containerId);
  var buttonId = listonicButtonIndex++;

  // Use indexed variables to support multiple buttons
  window['listonic_content_' + buttonId] = items.join('<br/>');
  window['listonic_name_' + buttonId] = listName;

  // Create iframe with unique ID
  var iframe = document.createElement('iframe');
  iframe.className = 'listonic_ifrm';
  iframe.id = 'listonic_ifrm_' + buttonId;
  iframe.frameBorder = '0';
  iframe.scrolling = 'no';
  container.appendChild(iframe);

  // Load script only once
  if (!listonicScriptLoaded) {
    var script = document.createElement('script');
    script.src = 'https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js';
    script.onload = function() { listonicScriptLoaded = true; };
    document.body.appendChild(script);
  }
}

Framework Integration#

The following examples show how to integrate Listonic buttons with popular JavaScript frameworks. These components handle proper cleanup and avoid common pitfalls like memory leaks.

React

import React, { useEffect, useRef } from 'react';

// Track script loading (shared across all instances)
let scriptLoaded = false;

const ListonicButton = ({ items, listName }) => {
  const containerRef = useRef(null);
  const iframeRef = useRef(null);
  const idRef = useRef('listonic_' + Date.now());

  useEffect(() => {
    const id = idRef.current;
    const container = containerRef.current;
    if (!container) return;

    // Clear previous content
    container.innerHTML = '';

    // Use indexed variables for unique identification
    window['listonic_content_' + id] = items.join('<br/>');
    window['listonic_name_' + id] = listName;

    // Create iframe with unique ID
    const iframe = document.createElement('iframe');
    iframe.className = 'listonic_ifrm';
    iframe.id = 'listonic_ifrm_' + id;
    iframe.frameBorder = '0';
    iframe.scrolling = 'no';
    container.appendChild(iframe);
    iframeRef.current = iframe;

    // Load script only once
    if (!scriptLoaded) {
      const script = document.createElement('script');
      script.src = 'https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js';
      script.onload = () => { scriptLoaded = true; };
      document.body.appendChild(script);
    }

    // Cleanup on unmount or when props change
    return () => {
      if (iframeRef.current && iframeRef.current.parentNode) {
        iframeRef.current.parentNode.removeChild(iframeRef.current);
      }
      delete window['listonic_content_' + id];
      delete window['listonic_name_' + id];
    };
  }, [items, listName]);

  return <div ref={containerRef} />;
};

export default ListonicButton;

Vue.js

<template>
  <div ref="container"></div>
</template>

<script>
// Track script loading (shared across all instances)
let scriptLoaded = false;

export default {
  props: {
    items: { type: Array, required: true },
    listName: { type: String, default: 'Shopping List' }
  },
  data() {
    return {
      instanceId: 'listonic_' + Date.now(),
      iframe: null
    };
  },
  mounted() {
    this.initButton();
  },
  beforeUnmount() {
    this.cleanup();
  },
  methods: {
    initButton() {
      const id = this.instanceId;

      // Use indexed variables for unique identification
      window['listonic_content_' + id] = this.items.join('<br/>');
      window['listonic_name_' + id] = this.listName;

      // Create iframe with unique ID
      this.iframe = document.createElement('iframe');
      this.iframe.className = 'listonic_ifrm';
      this.iframe.id = 'listonic_ifrm_' + id;
      this.iframe.frameBorder = '0';
      this.iframe.scrolling = 'no';
      this.$refs.container.appendChild(this.iframe);

      // Load script only once
      if (!scriptLoaded) {
        const script = document.createElement('script');
        script.src = 'https://s3-eu-west-1.amazonaws.com/buttons.listonic.pl/v1/button.js';
        script.onload = () => { scriptLoaded = true; };
        document.body.appendChild(script);
      }
    },
    cleanup() {
      if (this.iframe && this.iframe.parentNode) {
        this.iframe.parentNode.removeChild(this.iframe);
      }
      delete window['listonic_content_' + this.instanceId];
      delete window['listonic_name_' + this.instanceId];
    }
  }
}
</script>

Platform Guides#

WordPress

1. In the Gutenberg editor, add a "Custom HTML" block where you want the button
2. Paste the complete Listonic button code into the block
3. For the script, use a plugin like "Insert Headers and Footers" to add it site-wide, or include it in the Custom HTML block

Shopify

1. Go to Online Store → Themes → Edit code
2. Add the button HTML to your product template (product-template.liquid)
3. Add the Listonic script to theme.liquid before </body>

Wix

1. Add an "Embed" or "HTML iframe" element to your page
2. Paste the complete button code including the script
3. Adjust the element size to fit the button

Squarespace

1. Add a "Code" block to your page
2. Paste the complete Listonic button code
3. Save and preview the page

Troubleshooting#

Common Issues

Button doesn't appear

• Ensure the script URL is correct and accessible
• Check that the iframe element has the class listonic_ifrm
• Verify there are no JavaScript errors in the console
• Make sure listonic_content is defined before the script loads

Items not being added

• Check that items are separated by <br/> tags
• Ensure the content doesn't contain invalid HTML
• For the blog widget, verify the listonic_bw_generic_entryClass matches your HTML

Multiple buttons conflict

• Use indexed variables (_0, _1, etc.)
• Ensure each iframe has a unique ID

Browser Compatibility

The Listonic widget supports all modern browsers:

• Chrome (desktop and mobile)
• Firefox
• Safari (desktop and iOS)
• Edge

The widget uses standard JavaScript and iframe functionality supported by all modern browsers.

Debugging Tips

1. Open browser DevTools (F12) and check the Console for errors
2. Inspect the iframe to ensure it loaded correctly
3. Verify global variables are set: type listonic_content in the console
4. Check Network tab to ensure the script loaded (200 status)

Best Practices#

Performance & Script Placement

• Place scripts near the end of your document (before </body>) so they do not block initial page rendering
• For pages with many buttons, use indexed variables to avoid conflicts
• Load the Listonic script only once per page, even when using multiple buttons

HTML Structure Guidelines

• Keep ingredient lists in clean, semantic HTML structures (for example, unordered lists with list items) so the widget can parse them reliably
• Use consistent class names across your recipe pages
• Avoid nesting interactive elements inside list items

Accessibility

• The iframe content is accessible to screen readers
• Ensure sufficient color contrast if customizing colors
• The button is keyboard-navigable by default

Dynamic Content

• If you inject content dynamically (via AJAX or a frontend framework), ensure the Listonic scripts run after the content is present in the DOM
• When using multiple widgets or buttons, make sure each content wrapper has a unique class or identifier to avoid ambiguity
• Test your integration on both desktop and mobile devices to ensure a smooth user experience

API Reference#

Custom Button API

Automatic Button API

Script URLs

Frequently Asked Questions#

Installation Questions

Can I use the widget on any website?

Yes! The widget works on virtually any website or web application, including WordPress, Shopify, custom HTML sites, and modern JavaScript frameworks. As long as you can insert JavaScript into the page, you can use the Listonic Add-to-List button.

Do I need an API key?

No, the Listonic widget is free to use and doesn't require any API key or registration.

Is there a limit to how many buttons I can add?

No, you can add as many buttons as needed. Just use indexed variables for multiple buttons on the same page.

Customization Questions

Can I customize the button appearance?

Yes, you can customize colors using the styling script provided in the Styling section. For more extensive customization, consider using the Widget generator.

Can I change the button text?

Yes, set listonic_alternateText = 'true' to use "Add to shopping list" as the button text.

Technical Questions

Is the widget mobile-friendly?

Yes, the widget is fully responsive and works seamlessly on mobile devices. It connects directly with the Listonic app, which is used by over 20 million users worldwide.

Does the widget affect page load speed?

The widget is lightweight. For best performance, place the script near the end of your document (before </body>) so it doesn't block initial page rendering.

What happens when a user clicks the button?

The button opens the Listonic interface where users can add items to their shopping list. If they have the Listonic app, items sync automatically across their devices.

Live Examples#