The AMP runtime defines a small set of custom elements that can be used in any AMP file. These custom elements serve two primary purposes:
- Enable the AMP runtime to manage the loading of external resources, which may slow down the initial render or cause jank.
- Allow AMP authors to include functionality above and beyond standard HTML, while maintaining the security- and performance-minded requirement that no author-written JavaScript is executed.
The initial set of elements included in the AMP spec is purposefully minimal, to keep payload small. The AMP runtime also allows dynamic loading of additional ancillary components that have been contributed to the project.
The goal of the AMP components is to provide the correct set of primitives to AMP authors, such that a wide variety of experiences can be produced using only declarative HTML and CSS. AMP components are meant to be composed together to create more advanced and customized UI.
Styling and theming of AMP-provided components is all done via CSS. See the AMP Spec for more detail.
AMP HTML component style can be specified in two particular ways. Simple
elements such as amp-img can be styled with class or element selectors in an
author-defined, inlined stylesheet, using most common CSS properties. For
example:
<!doctype html>
<html ⚡>
<head>
<style>
amp-img {
border: 5px solid black;
}
amp-img.grey-placeholder {
background-color: grey;
}
</style>
</head>
<body>
<amp-img src="https://placekitten.com/g/200/300" width=200 height=300>
</amp-img>
<amp-img
class="grey-placeholder"
src="https://placekitten.com/g/500/300"
width=500
height=300>
</amp-img>
</body>
</html>AMP HTML components that are more complex and nested, such as amp-carousel,
may be styled with an explicitly defined set of CSS Custom Properties. These
are propagated to any children elements that are dynamically created by the
runtime, to achieve the desired style. This way the AMP author does not need to
know the internals of the component, only its styleable properties. For example:
<!doctype html>
<html ⚡>
<head>
<style>
amp-carousel {
--arrow-color: green;
--dots: {
opacity: 50%;
color: blue;
}
}
</style>
</head>
<body>
<amp-carousel width=500 height=500>
<div>
<amp-img width=500 height=500 src="https://placekitten.com/g/500/500">
</amp-img>
</div>
<div>
<amp-img width=500 height=500 src="https://placekitten.com/g/500/500">
</amp-img>
</div>
</amp-carousel>
</body>
</html>Inline style attributes are not allowed, as per the AMP spec.
All externally-loaded resources must have a known height at the time the page is loaded, so that as the resources load in the page doesn’t jump and reflow. Components are provided by the AMP runtime to enable loading these external resources, like amp-img, amp-video, etc. These components all share the following attributes:
width
The width of the component. width and height attributes imply the aspect ratio of the image, which can then scale with the container.
height
The height of the component. width and height attributes imply the aspect ratio of the image, which can then scale with the container.
layout
Defines the way the container is laid out. layout="responsive" will let the container scale with the width of the parent container. layout="nodisplay" indicates that the component should not be initially displayed by the runtime - for example, for an image that will appear in a lightbox when a trigger is tapped.
The AMP runtime itself will only build-in the most commonly-used components - additional components must be explicitly included into a AMP document.
The collection of official AMP components is open-source and open to contributions. To be considered for inclusion into the official AMP components, a contributed component must:
Use only the API surface area publicly specified by the AMP runtime to work. Be open-sourceable with an Apache 2 license and not minified or obfuscated. Have its behavior completely controllable by the runtime - e.g. not attempt to load resources outside of a timeframe allowed by the AMP runtime. Have a fixed, known aspect ratio at initial page load, except if placed at the bottom of the page. Not attempt to access or manipulate objects outside of the component’s immediate ownership - e.g. elements that are not specified by or children of the component. Not cause a AMP file to become invalid as per the AMP specification The author of the component must sign the Google Individual CLA, or if contributing on behalf of a corporation, the Corporate CLA. Like most open-source projects, the CLA protects Google, the contributor, and users from issues of intellectual property rights.
In the near-term, implementation will focus on the core components, before prioritizing extensibility. The long-term goal of the runtime though is to support this extensibility.
The creators of the AMP component project - Google and a core group of collaborators, and potentially representatives from other collaborators as the project grows in usage - will have ultimate discretion as to the inclusion of contributed components, though with the goal of including every high-quality contribution that meets the above guidelines, and resolving or providing feedback on proposed contributions in a timely manner.
While in active development, the initial creators of the project - Google and a core group of collaborators - will work together around adding additional owners as well as approving contributions for inclusion.
Contributions with the following characteristics will be prioritized:
- Generalized components that solve problems in a non-service-specific way - e.g. a “Related Content” widget that makes a request to a generic JSON endpoint for lazy-loading in additional content.
- Components that are modular, and useful for various types of contained content - e.g. a carousel that takes HTML as well as images.
A number of AMP components supporting features like ads, analytics, and embeds, may rely on third-party JavaScript provided by a specific service. For example: an analytics component from Google Analytics might need to run logic specific to the GA service, or a Twitter embed may need to run Twitter-specific code. There are three ways these service-specific components can work:
Arbitrary 3rd Party JavaScript loaded at runtime
AMP-conforming content may not have any JavaScript. Some components, like embedded ads, may require JavaScript to execute - these may only be used through AMP-provided components like amp-ad. The use of AMP-provided components ensures that any arbitrary 3rd-party JavaScript, in an embedded ad for example, must run in a sandboxed iframe.
Service-specific JavaScript built-in to a component
Specific services may contribute their own components to the expanded set of AMP components, which can then be loaded by a AMP file at runtime. These components may execute JavaScript in the context of the main page. They must conform to the specification provided in the “Third-Party Components” section in order to be included.
These types of components will be prioritized behind components that are more generalized, to work with a variety of services and endpoints.
Dynamic components from JSON endpoints
The AMP component set may provide components that can load data from an arbitrary endpoint at runtime and use that data to effect the layout and appearance of the component. For example, a “related articles” component may fetch JSON from a author-provided URL and use the data to populate a UI component.
In these cases, services may set up endpoints that produce data that conforms to how the component expects data to be returned. That component may then reference the endpoint with a url parameter for example, and the service will be effectively incorporated into the page.