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 targetId) exposes and you'd like to execute when the event is triggered.

AMP has a concept of a default action that elements can implement. So when omitting the methodName AMP will execute that default method.

arg=value no Some actions, if documented, may accept arguments. The arguments are defined between parentheses in key=value notation. The accepted values are:
  • simple unquoted strings: simple-value
  • quoted strings: "string value" or 'string value'
  • boolean values: true or false
  • numbers: 11 or 1.1
  • dot-syntax reference to event data: event.someDataVariableName

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.

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 user manually changes the carousel's current slide. Does not fire on autoplay or the goToSlide action.
// Slide number.
event.index

amp-selector

Event Description Data
select Fired when the user manually selects an option.
// The option attribute
// value of
// the selected element.
event.targetOption

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-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-live-list

Action Description
update (default) Updates the DOM items to show updated content.

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, 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:

  1. You can't give an arbitrary ID to this target. The target is always amp-access.
  2. The actions for amp-access are dynamic depending on the structure of the AMP Access Configuration.

See details about using the amp-access target.