CINXE.COM
AddToAny API & customization
<!DOCTYPE html> <html lang="en"> <head> <title>AddToAny API & customization</title> <meta name="viewport" content="width=device-width, initial-scale=1"> <link href="/css/main.18.min.css" rel="stylesheet"> <script>!function(){var e;(e=document.documentElement).className+=e.className?" svg":"svg";}();</script> <style> @media (prefers-reduced-motion: no-preference) { @view-transition { navigation: auto; } } </style> <script type="module" src="/js/prefetch.1.min.js"></script> <script blocking="render" defer src="/js/transition.1.min.js"></script> <link rel="expect" href="#header .logo :first-child" blocking="render" /> <link rel="expect" href="#header a[href='/share']" blocking="render" /> <style> table.api_chart td, table.api_chart th{text-align:left;padding:9px;vertical-align:top} table.api_chart td:first-child{font-family:Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace} table.api_chart tr:nth-child(odd){background:#f4f5f6} table.api_chart code{word-break:normal} </style> </head> <body> <div id="header"> <div class="header_content clearfix"> <div class="hdr_l"> <h2 class="logo"><a href="/" title="AddToAny Share Buttons">AddToAny</a></h2> </div> <div class="hdr_r"> <a class="hdr_link" href="/buttons/" title="Get the share buttons">Get</a> <a class="hdr_link" href="/buttons/customize/" title="Customize the share buttons">Customize</a> <a class="hdr_link" href="/share" title="Share a link">Share</a> <a class="hdr_link" href="/buttons/faq/" title="Frequently asked questions and answers">FAQ</a> </div> </div> </div> <div id="page"> <div class="main"> <h2>AddToAny JavaScript API</h2> <div class="notes"> <div class="notes_content"> <p><a href="#config">Configure</a> and <a href="#init">render</a> AddToAny with JavaScript, and <a href="#css">style</a> AddToAny with CSS.</p> <span id="config"></span> <h3>JavaScript Configuration Object</h3> <p> AddToAny JavaScript configuration consists of properties contained under the <code>a2a_config</code> object. See the <a href="/buttons/customize/">example code</a> for usage details. </p> <div class="table_responsive"> <table class="api_chart"> <tr> <th>Property name</th> <th>Default value</th> <th>Description</th> </tr> <tr> <td>icon_color</td> <td>Original colors</td> <td>Accepts a string containing the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/color_value" target="blank" rel="noopener">CSS color value</a>(s) to apply to all icons globally. See <a href="/buttons/customize/icon_color">custom color buttons</a> for details.</td> </tr> <tr> <td>native</td> <td>Unset</td> <td>Whether the native sharing mechanism of the device should be invoked instead of the AddToAny menu. A value of <code>false</code> disables native sharing and always shows the AddToAny menu. A value of <code>true</code> enables native sharing where available. By default, AddToAny enables the native sheet on operating systems with a thriving native app ecosystem such as Android and Apple touchscreen devices.</td> </tr> <tr> <td>onclick</td> <td><code>1</code></td> <td>If the value is <code>1</code> or a <em><a href="https://developer.mozilla.org/en-US/docs/Glossary/Truthy" target="_blank" rel="noopener">truthy</a></em> value, the "mini" menu will appear when the user <em>clicks</em> the button instead of when the user <em>hovers</em> over the button. If the value is <code>2</code>, the "full" universal menu will display on click.</td> </tr> <tr> <td>overlays</td> <td><code>[]</code></td> <td>Accepts an array of one or more AddToAny overlay configurations. By default, pushing an empty object to the array enables the <a href="/buttons/customize/image_sharing" title="Share buttons for images">image share buttons</a> overlay for sharing images.</td> </tr> <tr> <td>counts</td> <td><code>{}</code></td> <td>Accepts a configuration object for <a href="/buttons/customize/share_counters">share counts</a>, especially for <a href="/buttons/customize/share_count_recovery" title="Fix lost share counts when changing URLs">recovering share counts</a>.</td> </tr> <tr> <td>templates</td> <td><code>{}</code></td> <td>Customize endpoint parameters for any service, and change the default message for many services. See <a href="/buttons/customize/templates">AddToAny Templates</a> for details.</td> </tr> <tr> <td>callbacks</td> <td><code>[]</code></td> <td>Accepts an array of one or more callback objects to be invoked during specifc AddToAny events. Each <em>object</em> should contain <code>ready</code> and/or <code>share</code> properties whose values are a function or function reference. A function for the <code>share</code> event should have a single parameter whose argument will be an <em>object</em> with properties such as <code>node</code>, <code>service</code>, <code>title</code> and <code>url</code>. See <a href="/buttons/customize/events" title="Share event tracking, handling, and modifying">how to handle events</a> for details.</td> </tr> <tr> <td>delay</td> <td><code>0</code></td> <td>Hover/mouseover delay (in milliseconds) until the "mini" drop-down menu is displayed. A value between <code>50</code> and <code>500</code> is recommended if set.</td> </tr> <tr> <td>exclude_services</td> <td><code>false</code></td> <td>Accepts an array to remove specific services from the universal menus. See <a href="/buttons/customize/remove_services">how to remove services from AddToAny</a>.</td> </tr> <tr> <td>num_services</td> <td><code>10</code></td> <td>Number of services to be displayed by default within the "mini" drop-down menu.</td> </tr> <tr> <td>prioritize</td> <td>User's preferred services</td> <td>Specify the services you want to prioritize, ordered from highest priority to lowest priority. <br/> This is an array, so you can add as many services as you desire. <br/> See <a href="/buttons/customize/prioritize_services">how to force services to appear first in the menu(s)</a>. Note that the smart menu's personalization will give a user's preferred services highest priority.</td> </tr> <tr> <td>custom_services</td> <td><code>[]</code></td> <td>Add custom service(s) to the menu(s). This is an array, so you can add as many services as you desire. The icon URL is optional. See <a href="/buttons/customize/add_services">how to add custom services</a>.</td> </tr> <tr> <td>orientation</td> <td>Automatic</td> <td>Specify the vertical orientation of the "mini" menu. Accepts <code>down</code> or <code>up</code>.</td> </tr> <tr> <td>menu_type</td> <td>Unset</td> <td>If <code>"mail"</code>, the email menu is displayed. Accepts <code>"mail"</code> only.</td> </tr> <tr> <td>show_menu</td> <td>Unset</td> <td>Allows you to display the "mini" menu using <code>static</code>, <code>absolute</code>, <code>fixed</code>, or <code>relative</code> positioning, without needing a button. See the <a href="/buttons/customize/static_menu">static share menu example</a> for details.</td> </tr> <tr> <td>track_links</td> <td><code>false</code></td> <td>Shorten the URL or attach parameters to your shared link to get analytics on clickthrus. <br/> This will only modify shared links for services where shared link tracking is appropriate (e.g. sharing to Facebook, but not saving to Pocket). See <a href="/buttons/customize/link_tracking">how to enable tracking of shared links</a>.</td> </tr> <tr> <td>track_links_key</td> <td>Unset</td> <td>Used with the <code>track_links</code> property only, this accepts your URL shortener API key or a custom URL to use for shared links. See <a href="/buttons/customize/link_tracking">how to enable tracking of shared links</a>.</td> </tr> <tr> <td>localize</td> <td>Auto-localization</td> <td>Customize the language of the universal menu. See <a href="/buttons/customize/translation_localization">how to translate AddToAny yourself</a> or <a href="/buttons/translate/">how to submit default translations for AddToAny</a>.</td> </tr> <tr> <td>locale</td> <td><code>en-US</code></td> <td>Force the language of the universal menu and turn off auto-localization. Accepts a language code such as <code>"fr"</code> or <code>"fr-CA"</code> (ISO 639-1), or <code>"custom"</code> if you're providing <a href="/buttons/customize/translation_localization">your own AddToAny translation</a>.</td> </tr> <tr> <td>target</td> <td>Last uninitialized element with a class-name of <code>a2a_kit</code> or <code>a2a_dd</code></td> <td>Target specific DOM node(s) to initialize AddToAny on. Accepts a string containing a CSS selector for an ID (like <code>"#share-button"</code>) or class-name (like <code>".share-buttons"</code>), or an actual DOM node reference (like <code>document.getElementById('share-button')</code>).</td> </tr> <tr> <td>linkname</td> <td><code>document.title</code></td> <td>Title of the item to be shared. Will use the current page title to accomodate progressive web apps and Ajax-based sites, unless a value is explicitly set. <br> Instead of modifying this value, we recommend setting the title in a <code>data-a2a-title</code> attribute on an AddToAny Kit element. See <a href="/buttons/customize/single_button_specific_page">how to share a specific page</a> for details. </td> </tr> <tr> <td>linkurl</td> <td><code>location.href</code></td> <td>URL of the item to be shared. Will use the current URL (including the current hash) to accomodate progressive web apps and Ajax-based sites, unless a value is explicitly set. <br> Instead of modifying this value, we recommend setting the URL in a <code>data-a2a-url</code> attribute on an AddToAny Kit element. See <a href="/buttons/customize/single_button_specific_page">how to share a specific page</a> for details. </td> </tr> </table> </div> <p> See <a href="/buttons/customize/">AddToAny examples & documentation</a> for example code and live demonstrations. </p> <br id="init"> <h3>JavaScript Initialize & Render Functions</h3> <p>By default, AddToAny's <code>page.js</code> script initializes & renders all AddToAny HTML instances when the document is ready.</p> <p>AddToAny JavaScript functions can be used to initialize & render <em>new</em> AddToAny HTML instances inserted <em>after</em> the document is ready.</p> <p>The <code>a2a.init_all()</code> function is often used after content insertion via Ajax.</p> <div class="table_responsive"> <table class="api_chart"> <tr> <th>Function</th> <th>Description</th> </tr> <tr> <td><code>a2a.init_all()</code></td> <td>Initializes & renders all uninitialized AddToAny instances on the page.</td> </tr> <tr> <td><code>a2a.init('page')</code></td> <td>Initializes & renders only the last uninitialized AddToAny share buttons instance on the page.</td> </tr> <tr> <td><code>a2a.init('feed')</code></td> <td>Initializes & renders only the last uninitialized AddToAny <a href="/buttons/customize/follow_buttons" title="Social media links">follow buttons</a> instance on the page.</td> </tr> </table> </div> <p>These functions can only be used when the <code>page.js</code> script is loaded, so they are best used within an <a href="/buttons/customize/events">AddToAny <code>ready</code> callback</a>, or <em>conditionally</em> when <code>page.js</code> is probably already loaded:</p> <p><code>if (a2a) a2a.init_all()</code></p> <br id="css"> <h3>CSS Menu Overrides</h3> <p> AddToAny always keeps developers & designers in mind. We have a few tips for customizing the universal menus while maintaining <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Introduction_to_the_CSS_box_model" target="_blank" rel="noopener">box model</a> sizing calculations: </p> <ul> <li>You can override <code>padding</code>, fonts, and menu icon sizes.</li> <li>For menu icons, override <code>background-size</code>, <code>font-size</code>, <code>height</code>, <code>line-height</code>, and <code>width</code>.</li> <li>Avoid dimensional overrides (<code>height</code> & <code>width</code>) for most other elements.</li> <li>Apply <code>box-shadow</code> instead of changing the <code>border-size</code> of elements.</li> <li>Use the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity#The_!important_exception" target="_blank" rel="noopener"><code>!important</code></a> declaration as needed.</li> </ul> <p>We try to keep <code>class</code> and <code>id</code> names consistent with every release.</p> </div> </div> </div> <div id="footer"> <div class="footer_cols"> <div> <h2>Features</h2> <a href="/buttons/customize/floating_share_buttons" title="Floating Share Bars that are responsive for mobile and desktop, and can show and hide on scroll">Floating Share Buttons</a> <a href="/buttons/customize/image_sharing" title="Share your images directly to Facebook, Pinterest, Tumblr, Houzz, and more">Image Share Buttons</a> <a href="/buttons/customize/share_counters" title="Show the share count next to your share buttons">Share Counts</a> <a href="/buttons/customize/share_count_recovery" title="Recover lost share counts after a change in URLs, a new domain, or a move to HTTPS from HTTP">Share Count Recovery</a> <a href="/buttons/customize/follow_buttons" title="Link to your Instagram, Snapchat, YouTube, and other social media and RSS feeds">Follow Buttons</a> <a href="/ext/google_analytics/" title="Sharing analytics in Google Analytics">Google Analytics</a> </div> <div> <h2>Plugins</h2> <a href="https://wordpress.org/plugins/add-to-any/" title="Share Buttons for WordPress, the most popular WordPress sharing plugin">WordPress Share Plugin</a> <a href="https://www.drupal.org/project/addtoany" title="Share Buttons for Drupal, the most popular Drupal sharing module">Drupal Share Module</a> <a href="/buttons/for/joomla" title="Share Buttons for Joomla, available as a plugin and a module in one extension">Joomla Share Extension</a> <a href="https://www.cloudflare.com/apps/addtoany" title="Share Buttons for Cloudflare sites">Cloudflare Share App</a> <a href="/buttons/" title="All share button plugins for WordPress.com, Blogger, Tumblr, and more platforms, websites and apps">Share Buttons for Sites</a> <a href="/buttons/for/email_newsletter" title="Get share buttons for use in email">Share Buttons for Email</a> </div> <div> <h2>Browser Tools</h2> <a href="https://addons.mozilla.org/en-US/firefox/addon/addtoany-share/" title="Share button for Mozilla Firefox">AddToAny for Firefox</a> <a href="https://chrome.google.com/webstore/detail/addtoany-share-anywhere/ffpgijchhhkhnokafdeklpllijgnbche" title="Share button for Google Chrome">AddToAny for Chrome</a> <a href="/users/bookmarklet" title="Share button for your browser's Bookmarks Bar">AddToAny Bookmarklet</a> <a href="/services/" title="Services directory and bookmarklets">Service Bookmarklets</a> <a href="/share" title="Share a page to any service">Share a URL</a> <a href="/share/preferences" title="Set your preferred services">Sharing Preferences</a> </div> <div> <h2>Resources</h2> <a href="/buttons/customize/" title="Customize your share buttons">Customize AddToAny</a> <a href="/services/" title="Services directory and share button codes">Service Codes</a> <a href="/buttons/api/" title="JavaScript API reference">JavaScript API</a> <a href="/buttons/faq/" title="Answers to frequently asked questions">Questions & Answers</a> <a href="/blog/" title="The AddToAny Blog">AddToAny News</a> <a href="/contact/" title="Contact AddToAny">Contact AddToAny</a> </div> </div> <div class="legal"> <span>© 2006–2024</span> <a href="/terms" title="Terms of Service">Terms</a> <a href="/privacy" title="Privacy Policy">Privacy</a> </div> </div> </div></body> </html>