Actions and events
Important: this documentation is not applicable to your currently selected format email!
The on attribute is used to install event handlers on elements. The events that are supported depend on the element.
The value for the syntax is a simple domain-specific language of the form:
eventName:targetId[.methodName[(arg1=value, arg2=value)]]
See the table below for descriptions of each part of the syntax.
| Syntax | Required? | Description |
|---|---|---|
eventName | yes | This is the name of the event that an element exposes. |
targetId | yes | This is the DOM id for the element, or a predefined special target you'd like to execute an action on in response to the event. In the following example, the targetId is the DOM id of the amp-lightbox target, photo-slides. <amp-lightbox id="photo-slides"></amp-lightbox> <button on="tap:photo-slides">Show Images</button> |
methodName | no | This is for elements with default actions. This is the method that the target element (referenced by AMP has a concept of a default action that elements can implement. So when omitting the |
arg=value | no | Some actions, if documented, may accept arguments. The arguments are defined between parentheses in key=value notation. The accepted values are:
|
Handling multiple events
You can listen to multiple events on an element by separating the events with a semicolon ;.
Example: on="submit-success:lightbox1;submit-error:lightbox2"
Multiple actions for one event
You can execute multiple actions in sequence for the same event by separating the actions with a comma ','.
Example: on="tap:target1.actionA,target2.actionB"
Globally-defined events and actions
AMP defines a tap event globally that you can listen to on any HTML element (including AMP elements).
AMP also defines the hide, show and toggleVisibility actions globally that you can trigger on any HTML element.
An element can only be shown if it was previously hidden by a hide or toggleVisibility action, or by using the hidden attribute. The show action does not support elements hidden by CSS display:none or AMP's layout=nodisplay.
For example, the following is possible in AMP:
<div id="warning-message">Warning...</div> <button on="tap:warning-message.hide">Cool, thanks!</button>
Element-specific events
* - all elements
| Event | Description |
|---|---|
tap | Fired when the element is clicked/tapped. |
copy-success | Fired when the content/text is successfully copied into the clipboard. |
copy-error | Fired when there's an error while copying the content. If there's an error while copying the content, the event.data.type will be set to the error value. If the browser is not supporting the copy method, the event.data.type will be set to the browser value. |
Input elements
| Event | Description | Elements | Data |
|---|---|---|---|
change | Fired when the value of the element is changed and committed. Data properties mirror those in HTMLInputElement and HTMLSelectElement. | input | event.min event.max event.value event.valueAsNumber |
input[type="radio"],input[type="checkbox"] | event.checked | ||
select | event.min event.max event.value | ||
input-debounced | Fired when the value of the element is changed. This is similar to the standard change event, but it only fires when 300ms have passed after the value of the input has stopped changing. | Elements that fire input event. | Same as change event data. |
input-throttled | Fired when the value of the element is changed. This is similar to the standard change event, but it is throttled to firing at most once every 100ms while the value of the input is changing. | Elements that fire input event. | Same as change event data. |
amp-accordion > section
| Event | Description | Data |
|---|---|---|
expand | Fired when an accordion section expands. | None. |
collapse | Fired when an accordion section collapses. | None. |
amp-carousel[type="slides"]
| Event | Description | Data |
|---|---|---|
slideChange | Fired when the carousel's current slide changes. | // Slide number. event.index |
amp-lightbox
| Event | Description | Data |
|---|---|---|
lightboxOpen | Fired when lightbox is fully visible. | None |
lightboxClose | Fired when lightbox is fully closed. | None |
amp-list
| Event | Description | Data |
|---|---|---|
fetch-error(low-trust) | Fired when fetching data fails. | None |
amp-selector
| Event | Description | Data |
|---|---|---|
select | Fired when an option is selected or deselected. | // Target element's "option" attribute value. event.targetOption // Array of "option" attribute values of all selected elements. event.selectedOptions |
amp-sidebar
| Event | Description | Data |
|---|---|---|
sidebarOpen | Fired when sidebar is fully opened after transition has ended. | None |
sidebarClose | Fired when sidebar is fully closed after transition has ended. | None |
amp-state
| Event | Description | Data |
|---|---|---|
fetch-error(low-trust) | Fired when fetching data fails. | None |
amp-video and other Video Elements
The events below are dispatched by amp-video, amp-video-iframe and 3rd party video players like amp-youtube.
| Event | Description | Data |
|---|---|---|
firstPlay(low-trust) | Fired the first time the video is played by the user. On autoplay videos, this is fired as soon as the user interacts with the video. This event is low-trust which means it can not trigger most actions; only low-trust actions such as amp-animation actions can be run. | |
timeUpdate(low-trust) | Fired when the playing position of a video has changed. Frequency of the event is controlled by AMP and is currently set at 1 second intervals. This event is low-trust which means it can not trigger most actions; only low-trust actions such as amp-animation actions can be run. | {time, percent}time indicates the current time in seconds, percent is a number between 0 and 1 and indicates current position as percentage of total time. |
form
| Event | Description | Data |
|---|---|---|
submit | Fired when the form is submitted. | |
submit-success | Fired when the form submission response is success. | // Response JSON. event.response |
submit-error | Fired when the form submission response is an error. | // Response JSON. event.response |
valid | Fired when the form is valid. | |
invalid | Fired when the form is invalid. |
Element-specific actions
* (all elements)
| Action | Description |
|---|---|
hide | Hides the target element. |
show | Shows the target element. If an autofocus element becomes visible as a result, it gains focus. |
toggleVisibility | Toggles the visibility of the target element. If an autofocus element becomes visible as a result, it gains focus. |
toggleClass(class=STRING, force=BOOLEAN) | Toggles class of the target element. force is optional, and if defined, it ensures that class would only be added but not removed if set to true, and only removed but not added if set to false. |
toggleChecked(force=BOOLEAN) | Toggles checked state of the target element. force is optional, and if defined, it ensures that the resulting state would be identical to the value of force. |
scrollTo(duration=INTEGER, position=STRING) | Scrolls an element into view with a smooth animation.duration is optional. Specifies the length of the animation in milliseconds. If unspecified, an amount relative to scroll difference under or equal to 500 milliseconds is used.position is optional. One of top, center or bottom (default top). Specifies the position of the element relative to the viewport after scrolling.As an accessibility best practice, pair this with a call to focus() to focus on the element being scrolled to. |
focus | Makes the target element gain focus. To lose focus, focus on another element (usually parent element). We strongly advise against losing focus by focusing on body/documentElement for accessibility reasons. |
amp-audio
| Action | Description |
|---|---|
play | Plays the audio. Is a no-op if the <amp-audio> element is a descendant of <amp-story>. |
pause | Pauses the audio. Is a no-op if the <amp-audio> element is a descendant of <amp-story>. |
amp-bodymovin-animation
| Action | Description |
|---|---|
play | Plays the animation. |
pause | Pauses the animation. |
stop | Stops the animation. |
seekTo(time=INTEGER) | Sets the currentTime of the animation to the specified value and pauses animation. |
seekTo(percent=[0,1]) | Uses the given percentage value to determine the currentTime of the animation to the specified value and pauses animation. |
amp-accordion
| Action | Description |
|---|---|
toggle(section=STRING) | Toggles the expanded and collapsed states of amp-accordion sections. When called with no arguments, it toggles all sections of the accordion. Trigger on a specific section by providing the section id: on="tap:myAccordion.toggle(section='section-id')". |
expand(section=STRING) | Expands the sections of the accordion. If a section is already expanded, it stays expanded. When called with no arguments, it expands all sections of the accordion. Trigger on a specific section by providing the section id: on="tap:myAccordion.expand(section='section-id')". |
collapse(section=STRING) | Collapses the sections of the accordion. If a section is already collapsed, it stays collapsed. When called with no arguments, it collapses all sections of the accordion. Trigger on a specific section by providing the section id: on="tap:myAccordion.collapse(section='section-id')". |
amp-carousel[type="slides"]
| Action | Description |
|---|---|
goToSlide(index=INTEGER) | Advances the carousel to a specified slide index. |
toggleAutoplay(toggleOn=true|false) | Toggle the carousel's autoplay status. toggleOn is optional. |
amp-image-lightbox
| Action | Description |
|---|---|
open (default) | Opens the image lightbox with the source image being the one that triggered the action. |
amp-lightbox
| Action | Description |
|---|---|
open (default) | Opens the lightbox. |
close | Closes the lightbox. |
amp-lightbox-gallery
| Action | Description |
|---|---|
open | Opens the lightbox-gallery. Can be triggered by tapping another element, if you specify the image id: `on="tap:amp-lightbox-gallery.open(id='image-id')"`. |
amp-list
| Action | Description |
|---|---|
changeToLayoutContainer | Update's amp-list's layout to layout="CONTAINER" to allow dynamic resizing. |
refresh | Refreshes data from the src and re-renders the list. |
amp-live-list
| Action | Description |
|---|---|
update (default) | Updates the DOM items to show updated content. |
amp-selector
| Action | Description |
|---|---|
clear | Clears all selections from a defined amp-selector. |
selectUp(delta=INTEGER) | Moves the selection up by the value of `delta`. The default `delta` is set to -1. If no options are selected, the selected state will become the value of the last option. |
selectDown(delta=INTEGER) | Moves the selection down by the value of `delta`. The default `delta` is set to 1. If no options are selected, the selected state will become the value of the first option. |
toggle(index=INTEGER, value=BOOLEAN) | Toggles the application of the `selected`. If the select attribute is absent, this action adds it. If the select attribute is present, this action removes it. You may force and keep an add or remove by including a boolean value in the `value` argument. A value of `true` will force add the `selected` attribute and not remove it if already present. A value of `false` will remove the attribute, but not add it if absent. |
amp-sidebar
| Action | Description |
|---|---|
open (default) | Opens the sidebar. |
close | Closes the sidebar. |
toggle | Toggles the state of the sidebar. |
amp-state
| Action | Description |
|---|---|
refresh | Refetches data at the `src` attribute while ignoring browser cache. |
amp-user-notification
| Action | Description |
|---|---|
dismiss (default) | Hides the referenced user notification element. |
amp-video and other Video Elements
The actions below are supported in amp-video, amp-video-iframe and 3rd party video players like amp-youtube.
| Action | Description |
|---|---|
play | Plays the video. |
pause | Pauses the video. |
mute | Mutes the video. |
unmute | Unmutes the video. |
fullscreenenter | Takes the video to fullscreen. |
form
| Action | Description |
|---|---|
clear | Clears any values in the form's inputs. |
submit | Submits the form. |
Special targets
The following are targets provided by the AMP system that have special requirements:
Target: AMP
The AMP target is provided by the AMP runtime and implements top-level
actions that apply to the whole document.
| Action | Description | ||
|---|---|---|---|
navigateTo(url=STRING, target=STRING, opener=BOOLEAN) | Navigates current window to given URL, to the optional specified target if given (currently only supporting Caveat: Using normal | ||
closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN) | Tries to close the window if allowed, otherwise it navigates similar to Caveat: Using normal | ||
goBack(navigate=BOOLEAN) | Navigates back in history. `navigate` is optional, and if set to true, allows for cross-document navigation similar to [history.back](https://developer.mozilla.org/en-US/docs/Web/API/History/back). | ||
print | Opens the Print Dialog to print the current page. | ||
| scrollTo(id=STRING, duration=INTEGER, position=STRING) | Scrolls to the provided element ID on the current page. | ||
| optoutOfCid | Opts out of Client ID generation for all scopes. | ||
setState({foo: 'bar'})1 | Requires amp-bind. Merges an object literal into the bindable state. | ||
pushState({foo: 'bar'})1 | Requires amp-bind. Merges an object literal into the bindable state and pushes a new entry onto browser history stack. Popping the entry will restore the previous values of variables (in this example, | ||
copy(text='content') | Copy any content to the clipboard. | toggleTheme() | Toggles the amp-dark-mode class on the body element when called and sets users preference to the localStorage. The amp-dark-mode class is added by default to body based on the prefers-color-scheme value. Use data-prefers-dark-mode-class attribute on body tag to override the class to be used for dark mode. |
1When used with multiple actions, subsequent actions will wait for setState() or pushState() to complete before invocation. Only a single setState() or pushState() is allowed per event.
Target: amp-access
The amp-access target is provided by the amp-access component.
The amp-access target is special for these reasons:
- You can't give an arbitrary ID to this target. The target is always
amp-access. - The actions for
amp-accessare dynamic depending on the structure of the AMP Access Configuration.
See details about using the amp-access target.