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

widget/listonic-button.js

Basic Implementation

<!-- Items to be added – HTML links supported -->
<div class="listonic-button"
     data-items="item <a href='http://example.com'>one</a>, item two"
     data-name="My shopping list">
</div>
<script src="widget/listonic-button.js" defer></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

widget/listonic-auto.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>
  var listonic_auto = {
    entryClass: "recipe__wrapper__list",
    hideSideBar: true
  };
</script>
<script src="widget/listonic-auto.js" defer></script>

How Automatic Extraction Works

The widget scans the HTML element specified by the entryClass property 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, simply use multiple <div class="listonic-button"> elements. The script only needs to be included once.

<!-- First button -->
<div class="listonic-button"
     data-items="Milk, Eggs"
     data-name="Breakfast">
</div>

<!-- Second button -->
<div class="listonic-button"
     data-items="Chicken, Rice, Vegetables"
     data-name="Dinner">
</div>

<!-- Include the script once -->
<script src="widget/listonic-button.js" defer></script>

Custom Button Parameters#

Automatic Button Parameters#

The Automatic Button is configured using the listonic_auto object. Set its properties before loading the script.

Button Styling#

Customize the look and feel of your Listonic button using the data-style attribute. Pass a JSON object with the styling properties you want to override.

Custom Styling#

Use the data-style attribute on any button element to apply custom styles:

<div class="listonic-button"
     data-items="Milk, Eggs, Bread"
     data-name="My List"
     data-style='{
       "primaryColor": "#FF6B35",
       "iconColor": "#ffffff",
       "textColor": "#ffffff",
       "borderRadius": "50px",
       "fontFamily": "Roboto, sans-serif",
       "fontSize": "16px",
       "fontWeight": "600",
       "buttonText": "Add to shopping list",
       "iconStyle": "shopping-cart"
     }'>
</div>
<script src="widget/listonic-button.js" defer></script>

Available Style Properties

Dynamic Content (AJAX/SPAs)#

If you inject content dynamically (for example, via AJAX or a frontend framework), you can create and initialize Listonic buttons programmatically using the ListonicButton.initButton API.

// After your content is loaded via AJAX
function addListonicButton(items, listName, containerId, style) {
  const container = document.getElementById(containerId);

  // Create button element with data attributes
  const el = document.createElement('div');
  el.className = 'listonic-button';
  el.dataset.items = items.join(', ');
  el.dataset.name = listName;
  if (style) {
    el.dataset.style = JSON.stringify(style);
  }
  container.appendChild(el);

  // Initialize the button via the public API
  if (window.ListonicButton) {
    window.ListonicButton.initButton(el);
  }
}

Framework Integration#

The following examples show how to integrate Listonic buttons with popular JavaScript frameworks. These components use the v2 data-* attributes and ListonicButton.initButton API.

React

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

const ListonicButton = ({ items, name, style }) => {
  const ref = useRef(null);

  useEffect(() => {
    if (ref.current && window.ListonicButton) {
      window.ListonicButton.initButton(ref.current);
    }
  }, [items, name]);

  return (
    <div
      ref={ref}
      className="listonic-button"
      data-items={items}
      data-name={name}
      data-style={style ? JSON.stringify(style) : undefined}
    />
  );
};

export default ListonicButton;

Vue.js

<template>
  <div ref="buttonEl"
       class="listonic-button"
       :data-items="items"
       :data-name="name"
       :data-style="styleJson"></div>
</template>

<script>
export default {
  props: {
    items: { type: String, required: true },
    name: { type: String, default: 'Shopping List' },
    style: { type: Object, default: null }
  },
  computed: {
    styleJson() {
      return this.style ? JSON.stringify(this.style) : undefined;
    }
  },
  mounted() {
    if (window.ListonicButton) {
      window.ListonicButton.initButton(this.$refs.buttonEl);
    }
  }
}
</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 container element has the class listonic-button
• Verify there are no JavaScript errors in the console
• Make sure data-items is set on the element before the script loads

Items not being added

• Check that items are separated by commas in the data-items attribute
• Ensure the content doesn't contain invalid HTML
• For the automatic button, verify the entryClass in listonic_auto matches your HTML

Multiple buttons conflict

• Use separate <div class="listonic-button"> elements for each button
• Include the script only once on the page

Browser Compatibility

The Listonic widget supports all modern browsers:

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

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

Debugging Tips

1. Open browser DevTools (F12) and check the Console for errors
2. Inspect the button element to ensure it has the correct data-* attributes
3. Verify the public API is available: type window.ListonicButton in the console
4. Check Network tab to ensure the script loaded (200 status)

Best Practices#

Performance & Script Placement

• Place the script tag with defer attribute so it does not block initial page rendering
• For pages with many buttons, use separate <div class="listonic-button"> elements — the script handles them all
• 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 button is rendered as a native HTML element, 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), use ListonicButton.initButton(el) to initialize new button elements after they are added to the DOM
• When using multiple buttons, each <div class="listonic-button"> element is independent — no special configuration needed
• 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 separate <div class="listonic-button"> elements — the script initializes them all automatically.

Customization Questions

Can I customize the button appearance?

Yes, you can customize colors and other styles using the data-style attribute. See the Styling section for all available properties. You can also use the Widget generator for a visual editor.

Can I change the button text?

Yes, use the buttonText property in the data-style attribute to set any custom label, for example: data-style='{"buttonText":"Add to shopping list"}'.

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. The script uses the defer attribute, so it loads without blocking 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#