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.
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. |
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-carousel[type="slides"]
Event | Description | Data |
---|---|---|
slideChange |
Fired when the carousel's current slide changes. | // Slide number. event.index |
toggleAutoplay |
Will, on user tap or click, toggle the autoplay status for the carousel. You can either specify the status you want by specifying it: carousel-id.toggleAutoplay(toggleOn=false) or flip the status by not specifying a value. |
optional toggle status |
amp-lightbox
Event | Description | Data |
---|---|---|
lightboxOpen |
Fired when lightbox is fully visible. | None |
lightboxClose |
Fired when lightbox is fully closed. | None |
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-video, amp-youtube
Event | Description | Data |
---|---|---|
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. |
toggleVisibility |
Toggles the visibility of the target element. |
scrollTo(duration=INTEGER, position=STRING) |
Scrolls an element into view with a smooth animation. If defined,
duration specifies the length of the animation in milliseconds
(default is 500ms). position is optional and takes one of
top , center or bottom defining where
in the viewport the element will be at the end of the scroll (default is
top ). |
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-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. |
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-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-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-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 |
---|---|
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) |
Navigates current window to given URL. Supports standard URL substitutions. |
goBack |
Navigates back in history. |
print |
Opens the Print Dialog to print the current page. |
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, |
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.
See details about using the amp-access
target.