Share buttons JavaScript API

Loading

<script async src="//static.addtosite.com/widget.js"></script>

Set options before the script runs. Custom services and initial markup are initialized at load; menu, payload and event settings are read when used. refresh() initializes new markup rather than rebuilding existing kits.

<script>
  window.ats_config = window.ats_config || {};
  window.ats_config.num_services = 5;
  window.ats_config.track = false;
</script>

Options

Everything below goes in one object on window.ats_config. Leave a key out and the widget uses the default shown here.

Key	Type	Default	Effect
`url`	string	`Page canonical URL, then location.href`	Default link to share. A kit’s data-url takes priority.
`title`	string	`og:title, then document.title`	Default message/title. A kit’s data-title takes priority.
`image`	string	`og:image, then empty`	Image URL for endpoints such as Pinterest. A kit’s data-image takes priority.
`num_services`	number	`No limit`	Maximum inline service buttons. An empty kit uses the default catalog set; More offers the remaining allowed services.
`native`	boolean	`Automatic on mobile/touch`	Use the device share sheet when available. true also enables it on desktop; false always uses the widget menu.
`lang`	string	`Page language, then browser language`	Explicit locale wins. Supported base codes: en, vi, de, fr, es, pt, ja, zh. Regional codes use their base language; unsupported explicit/page languages fall back to English.
`strings`	object	`{}`	Override individual labels: share, more, search, close, copied, shareTo, noResults, followOn, shareCount, shareFailed. Empty or invalid values fall back to the selected language.
`theme`	string	`Operating-system preference`	light or dark pins widget surfaces to your site theme. Call addtosite.theme() to update surfaces already rendered.
`services`	string[] or string	`All available services`	Allowlist of service keys, also accepted as comma-separated text. An empty list leaves all services available.
`exclude_services`	string[] or string	`[]`	Exclude these services when no nonempty allowlist is set. A nonempty services list takes priority.
`priority`	string[] or string	`[]`	Order these services first, followed by saved preferences and then catalog order. Filtering and platform restrictions still apply.
`custom_services`	object[]	`[]`	Register services before loading: key, name, color, and url and/or follow. Optional fg and HTTP(S) icon URL. URL templates use {url}, {title}, {image}; follow uses {handle}.
`share_url`	object	`{}`	Replace service endpoint templates by key. Supports {url}, {title}, {image}; accepted schemes are HTTP(S), mailto and sms.
`mastodon_instance`	string	`mastodon.social`	Mastodon server used for share and follow URLs.
`menu_type`	string	`All share services`	mail restricts universal and quick menus to supported email providers; it also bypasses automatic native sharing.
`menu_search`	boolean	`true`	Show the search field in the full menu.
`menu_trigger`	string	`click`	hover opens the full menu after hover_delay. Click and keyboard activation remain available; touch uses click.
`hover_delay`	number	`200`	Hover delay in milliseconds, bounded to 0–2000. Leaving the trigger cancels the pending open.
`quick_menu`	boolean or string	`Off`	true or click opens a compact menu on click; hover opens on hover; static keeps it visible. quick_count, quick_orientation or quick_position also enable it.
`quick_count`	number	`6`	Compact-menu service count, from 1 to 24. More remains available.
`quick_orientation`	string	`horizontal`	horizontal or vertical button arrangement in the compact menu.
`quick_position`	string	`auto`	auto opens below and flips upward when needed; up or down forces the opening direction. This does not change the row/column arrangement or a static menu.
`track`	boolean	`true`	Send anonymous widget-action pings. false stops these pings; it does not disable count reads or your page’s analytics integration.
`analytics`	boolean	`true`	Report share events to an existing gtag or dataLayer. No analytics library is loaded. false disables this independently of track.
`counters`	boolean	`false`	Fetch and show this widget’s recorded action counts on service buttons. These are not network-wide popularity or confirmed published posts.
`api`	string	`//data.addtosite.com/v1`	Counting API base URL for a self-hosted backend. Sharing never waits for this service.
`link_campaign`	string	`Unset`	Add utm_source=<service>, utm_medium=social and utm_campaign=<value> to shared URLs. Existing values for these parameters are replaced.
`shorten`	function	`Unset`	Receives the campaign URL and returns an HTTP(S) URL or Promise. Popup shares fall back after an error or 3-second timeout. Native sharing and local actions do not wait for this hook.
`ready`	function or function[]	`Unset`	Receives the API once after the initial document scan. Use it for code that requires the asynchronously loaded widget.
`onBeforeShare`	function or function[]	`Unset`	Receives {service, url, title, image}. Modify the payload, or return false to cancel.
`onShare`	function or function[]	`Unset`	Runs after a popup opens, a local action succeeds or the native share Promise resolves. It does not confirm publication on a network.
`dock_after`	number	`0`	For floating bars, scroll distance in pixels before showing the bar. Zero disables scroll-based hiding.
`dock_until_foot`	number	`0`	With dock_after enabled, hide the floating bar this many pixels before the document bottom.
`overlays`	boolean	`false`	Enable image share overlays; loads overlays.js beside widget.js.
`overlay_min_size`	number	`200`	Both rendered image dimensions must meet this size in pixels.
`overlay_target`	string	`All eligible images`	CSS selector restricting images. Header/footer/widget images, hidden images and data-ats-no-overlay ancestors are excluded.
`overlay_show`	string	`hover`	visible keeps buttons displayed, including on touch screens. hover reveals them on hover or tap.
`overlay_services`	string[]	`["pinterest", "dd"] when customized`	Service keys in overlay order; dd means More. The basic uncustomized overlay uses one universal button.
`overlay_size`	number	`32`	Image button size, bounded to 16–64 pixels.
`overlay_orientation`	string	`vertical`	horizontal or vertical layout for customized image buttons.
`overlay_position`	string	`top-left`	Vertical position top/center/bottom plus horizontal left/center/right, for example bottom-center.
`overlay_use_image`	boolean	`false`	Share the image file URL. Otherwise share longdesc, the canonical page URL or location.href; the image itself still fills {image}.
`overlay_html`	string	`Unset`	Trusted HTML containing one ats_kit root. Replaces overlay services/size/orientation markup while keeping position and image context.

Markup contract

A kit is any element with the ats_kit class. Its children carry ats_btn_<service> classes, in the order you want them shown. An empty kit falls back to the default set.

<div class="ats_kit ats_kit_size_32">
  <a class="ats_btn_facebook"></a>
  <a class="ats_btn_x"></a>
  <a class="ats_dd"></a>
</div>

Use ats_follow instead of ats_kit for profile links. ats_kit_size_16 through ats_kit_size_64 set icon size; the default is 32. ats_counter requests a large count on a button, including More. Shape classes are ats_round_style and ats_square_style. Floating bars use ats_floating_style with horizontal or vertical placement; see the floating-bar guide for its CSS.

Attribute	On	Effect
`data-url`	kit or standalone button	Share this URL instead of the current page
`data-title`	kit or standalone button	Share this title instead of the document title
`data-also`	kit	Previous addresses of this page, comma separated, whose counts should be added in
`data-image`	kit or standalone button	Image URL for Pinterest and custom endpoint templates
`data-label`	button	Show this text beside the icon
`data-handle`	follow button	Profile handle or full profile URL; required inside ats_follow
`data-ats-keep`	button	Preserve your own image/text markup inside the button
`data-ats-no-overlay`	image or ancestor	Exclude the image or subtree from image sharing overlays
`longdesc / alt`	image	Image-overlay link target and title; image URL is still available to Pinterest

Methods

window.ats and window.addtosite expose the same API. Call methods after the ready hook, or check that the API exists. Preference storage belongs to the current origin; it does not synchronize across unrelated websites.

Signature	Behaviour
`addtosite.refresh(root?)`	Initialize unprocessed share/follow kits and standalone buttons in the document or supplied DOM subtree. Includes root itself. Already initialized elements are left intact.
`addtosite.share(key, context?)`	Activate an available share service. Context accepts url, title and image; omit it to use the page defaults. Follow-only and unknown service keys do nothing.
`addtosite.menu(context?)`	Open the share menu or eligible native sheet, respecting native and menu_type. Set native:false for the widget menu.
`addtosite.nativeShare(context?)`	Call from a click or keyboard handler to request native sharing. Returns Promise<boolean>: true on native completion, false on cancellation/fallback. Unsupported or failed sharing opens the widget menu; dismissing the native sheet stays quiet.
`addtosite.preferences()`	Return a copy of the saved preferred service keys for this origin.
`addtosite.preferences(keys)`	Save an ordered array of share-service keys and update quick menus. Unknown/duplicate keys are removed. Pass [] to clear. Uses localStorage key ats-preferred-services on the current origin, with in-memory fallback when storage is unavailable.
`addtosite.close()`	Close the widget full and quick menus. The operating system controls its own native sheet.
`addtosite.theme(value?)`	Set light, dark or auto and repaint existing surfaces. With no argument, re-read ats_config.theme. Returns the forced theme, or null for automatic.
`addtosite.t(key, values?)`	Resolve an interface label using strings overrides and the selected locale. Example: addtosite.t("shareTo", {name:"X"}).
`addtosite.services`	Runtime catalog, including custom entries. Each entry has key, name, color and either url/action and/or follow. Not every entry supports sharing.
`addtosite.version`	Version string of the loaded widget.

Counting endpoints

Served from data.addtosite.com. Sharing sends a fire-and-forget action ping; counters separately fetch the count endpoint. A backend outage does not prevent sharing. Counts describe recorded widget actions, not total shares reported by social networks.

Method	Endpoint	Purpose
POST	`//data.addtosite.com/v1/share`	Records one widget action, not a confirmed published post. Sent by the widget with sendBeacon; the site domain is taken from the Origin header, never from the body.
GET	`//data.addtosite.com/v1/count?url=&also=`	Per-service counts for one URL. The URL is canonicalised first, so scheme, www, a trailing slash and campaign parameters do not split a page in two. `also` takes up to five previous addresses, comma separated, and folds their counts in.
GET	`//data.addtosite.com/status`	Liveness check.