docs/concepts/session/element.md

# Elements

*tl;dr:* Elements are components added to a session as a result of user
interaction, similar to "apps" on other platforms.

This document provides a brief conceptual overview of elements, element
annotations, and their relationship to [components][doc-component].

## Elements are components

Elements are [components][doc-component] with key-value annotations. All
elements are implemented as components. While any component could hypothetically
be instantiated as an element, elements [contribute more directly](#element-ui)
to the user experience of a product, much like an "app" would on other
platforms.

Since elements are components, they inherit all component properties, such as:

* Elements are identified by their component URL, and have a [component
  manifest][doc-component-manfest].
* Elements participate in [capability routing][doc-capability-routing].

Elements are typically instantiated in [component
collections][doc-component-collection] within the session component.

## Elements provide a UI {#element-ui}

Elements contribute to the user experience of a product by providing a visual,
audible, or other discernible interaction with the user. The specific modes of
interaction available to, and expected from, an element, are defined by the
product and its configuration. The most common mode of output is graphical.

## Elements have annotations {#element-annotations}

Every element has an associated list of mutable key-value annotations, set first
when the element instance is added to a product experience at runtime. Element
annotations are used by the product's "user experience presenter" to control
details of the element's presentation. For example, for graphical elements
annotations may specify if presentation should hide system chrome, allow for
certain types of gestures, and so on.

## Elements are portable across products

Elements are an abstraction intended to make it easier to interactively run
components on many different Fuchsia products and varying product
configurations. An element's primary interaction surface with a product are
defined by:

* The mechanism by which it presents itself (graphically using Scenic, through
  audio, and so on).
* The mechanism by which it receives user input (finger touches, gestures,
  keyboard, and so on).
* The semantic meaning associated with its various annotations.

Although none of these mechanisms are strictly defined by the Fuchsia platform,
some are standardized and intended to be re-used across all products built with
Fuchsia.

For example, the specific meanings of different annotation keys and their
respective values are not prescribed by the Fuchsia platform. Some keys
have recommended meanings, with recommended standard schemas.

## Further reading

* [Graphical Presenter][doc-graphical-presenter]: a component role and protocol
  for presenting elements using Fuchsia's graphical compositor,
  [Scenic][doc-scenic].

[doc-component]: /docs/concepts/components/v2/introduction.md
[doc-component-manifest]: /docs/concepts/components/v2/component_manifests.md
[doc-capability-routing]: /docs/concepts/components/v2/topology.md#capability-routing
[doc-scenic]: /docs/concepts/graphics/scenic/scenic.md
[doc-component-collection]: /docs/concepts/components/v2/realms.md#collections