Autocapture Plugin

Amplitude's Autocapture plugin extends the events and properties that Amplitude tracks by default, and enables Visual Labeling to enable you to define events based on elements on your site. For more information about Visual Labeling, see Visual Labeling.


Autocapture requires the latest versions of the Amplitude Browser SDK (2.9.0) and the Autocapture plugin (0.9.0)

1<script defer src=""></script>
2<script defer src=""></script>

1npm install @amplitude/analytics-browser
2npm install @amplitude/plugin-autocapture-browser@beta

1yarn add @amplitude/analytics-browser
2yarn add @amplitude/plugin-autocapture-browser@beta

Initialize the plugin

The Amplitude Browser SDK supports a plugin architecture that enables features like Autocapture. To enable the plugin, update your code with one of the following snippets, depending on your implementation. Both methods require that you define the Autocapture plugin, then call add() to enable it.

1<script type="module">
2 window.amplitude.init(AMPLITUDE_API_KEY)
3 const autocapturePlugin = window.amplitudeAutocapturePlugin.plugin();
4 window.amplitude.add(autocapturePlugin);

1import * as amplitude from '@amplitude/analytics-browser';
2import { autocapturePlugin } from '@amplitude/plugin-autocapture-browser';


The Autocapture plugin adds four settings that help you configure what the plugin tracks.

Default Description
cssSelectorAllowlist ['a','button','input','select','textarea','label','[data-amp-default-track]','.amp-default-track'] String[]. Accepts one or more CSS selectors that define which elements on the page to track.
pageUrlAllowlist undefined `(string
shouldTrackEventResolver undefined Function. Programatically determines if Amplitude should or shouldn't track an event.
dataAttributePrefix data-amp-track Allows the plugin to capture data attributes as an event property
1const plugin = autocapturePlugin({
2 cssSelectorAllowlist: [
3 '.amp-tracking',
4 '[amp-tracking]'
5 ],
6 pageUrlAllowlist: [
7 '',
8 new RegExp('*')
9 ],

By default, if you don't use these settings, Amplitude tracks the default selectors on all page on which you enable the plugin.


When specify the CSS selectors to track, your selection overrides the default. To retain the default selectors import the DEFAULT_CSS_SELECTOR_ALLOWLIST and include it in your code.

1import { DEFAULT_CSS_SELECTOR_ALLOWLIST } from '@amplitude/plugin-autocapture-browser';
3const selectors = [
5 '.class-of-a-thing-i-want-to-track',

New events

When you enable the Autocapture plugin, Amplitude sends two events, from which you can create Labeled Events with Visual Labeling:

  • [Amplitude] Element Clicked
  • [Amplitude] Element Changed

These two events capture properties that describe the corresponding element and other context about the user's browser:

  • [Amplitude] Element ID
  • [Amplitude] Element Class
  • [Amplitude] Element Tag
  • [Amplitude] Element Text (Collected for [Amplitude] Element Clicked, only)
  • [Amplitude] Element Href (Collected for [Amplitude] Element Clicked, only)
  • [Amplitude] Element Position Left
  • [Amplitude] Element Position Top
  • [Amplitude] Viewport Height
  • [Amplitude] Viewport Width
  • [Amplitude] Page URL
  • [Amplitude] Page Title
  • [Amplitude] Element Selector
  • [Amplitude] Element Attributes
  • [Amplitude] Element Aria Label
  • [Amplitude] Element Parent Label

Disable Autocapture

To disable Autocapture, remove the plugin from any pages that implement it, and set defaultTracking: false in the Amplitude initialization on that page.

Remove the following lines of code:

1<!-- load Amplitude Autocapture plugin -->
2<script defer src=""></script>
3<!-- initialize Amplitude SDK and Autocapture plugin -->
4<script type="module">
5 const autocapturePlugin = window.amplitudeAutocapturePlugin.plugin();
6 window.amplitude.add(autocapturePlugin);

Remove the plugin:

1// npm
2npm uninstall @amplitude/plugin-autocapture-browser
4// yarn
5yarn remove @amplitude/plugin-autocapture-browser

Remove the initialization code:

1// Remove the following lines of code
2import { autocapturePlugin } from '@amplitude/plugin-autocapture-browser';

Was this page helpful?

Thanks for your feedback!

June 17th, 2024

Need help? Contact Support


Have a look at the Amplitude Blog

Learn more at Amplitude Academy

© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.