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.
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.
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-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, 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.
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.
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-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
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
selectUp(delta=INTEGER)
Moves the selection up by the value of delta. The default delta is set to 1.
selectDown(delta=INTEGER)
Moves the selection down by the value of delta. The default delta is set to -1.
toggle(index=INTEGER, value=BOOLEAN)
Sets the selected element's selected attribute if value is 'true', otherwise removes the attribute
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.
Video elements
The actions below are supported in the following AMP video elements: amp-video, amp-youtube, amp-3q-player, amp-brid-player, amp-dailymotion, amp-delight-player, amp-ima-video.
Action
Description
play
Plays the video.
pause
Pauses the video.
mute
Mutes the video.
unmute
Unmutes the video.
fullscreen
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.
Navigates current window to given URL, to the optional specified target if given (currenly only supporting _top and _blank ). The optional opener parameter can be specified when using a target of _blank to allow the newly opened page to access window.opener. Supports standard URL substitutions.
Tries to close the window if allowed, otherwise it navigates similar to navigateTo Action. Useful for use-cases where a "Back" button may need to close the window if it were opened in a new window from previous page or navigate if it wasn't opened.
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, foo).
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-access are dynamic depending on the structure of the AMP Access Configuration.
We use cookies to understand how you use our site and to improve your experience. By continuing to use our site, you accept our use of cookies and privacy policy.