Elix render pipeline

Elix components use a functional-reactive programming (FRP) architecture. To achieve high quality, reliable behaviors across a large number of components, the project breaks down component behaviors in mixins. These mixins cooperate with each other, generally handling a specific point in a rendering pipeline:

events → methods → setState → updates → render DOM → post-render

  1. User activity generates DOM events, such as a keydown or touchstart event. User activity can also trigger application behavior that produces custom element lifecycle callbacks (e.g., attributeChangedCallback). These can also be considered events in this pipeline.
  2. Event handlers respond by invoking methods or setting properties on the component. (In very simple cases, an event handler skip this step, and directly call setState to update component state.)
  3. Component methods/properties in turn update component state. The method/property may call setState directly, or it might invoke another method/property that ultimately calls setState.
  4. The component is asked to translate the component's new state into updates it would like to apply to the DOM. See RenderUpdatesMixin for details on how these updates are specified.
  5. The component renders the above updates to the DOM. Alternatively, the component may implement an internal render method that modifies the DOM directly.
  6. In rare cases, the component may need to perform post-render work that can only happen after the DOM has updated, such as update keyboard focus.

Mixins that handle events (events → methods)

Some of these mixins directly update state.

  • ArrowDirectionMixin. Adds left/right buttons that map to goLeft/goRight methods.
  • AttributeMarshallingMixin. Maps attributes to properties.
  • ClickSelectionMixin. Maps clicks on items to setting selectedIndex property.
  • ComposedFocusMixin. Normalizes focus treatment for custom elements with Shadow DOM.
  • DarkModeMixin. Lets a component automatically or explicitly configure itself for dark backgrounds.
  • FocusVisibleMixin. Tracks whether to show a focus indicator, sets state.focusVisible.
  • HoverMixin. Maps mouseenter/mouseleave events to state.hover.
  • KeyboardMixin. Maps keydown events to keydown method.
  • PopupModalityMixin. Maps blur and various window/document events to close method.
  • ResizeMixin. Maps changes in window or component size to clientHeight/clientWidth state members.
  • SlotContentMixin. When the component's slot receives a slotchange event, this updates state.content with the new nodes assigned to the slot.
  • TouchSwipeMixin. Maps touch swipe gestures to state.swipeFraction and swipeLeft/swipeRight methods.
  • TrackpadSwipeMixin. Maps trackpad gestures to state.swipeFraction and swipeLeft/swipeRight methods.
  • TransitionEffectMixin. Manages state changes that depend upon completion of CSS transitions.

Mixins that map methods to other methods

These mixins generally map from a low-level abstraction (e.g., a specific type of key has been pressed) to a higher-level abstraction (something should be selected).

Mixins that update state (methods → setState)

  • CalendarElementMixin. Adds locale-dependent date support to an element in a calendar.
  • OpenCloseMixin. Tracks the opened/closed state, providing open/close methods that set a state.opened member.
  • SelectedItemTextValueMixin. Supplies a value property that gets/sets the item specified by a selectedIndex property.
  • SingleSelectionMixin. Maps selection methods like selectPrevious/selectNext to changes in state.selectedIndex.

Mixins that translate state into updates (setState → updates)

  • AriaListMixin. Renders state.selectedIndex as various ARIA attributes like aria-activedescendant.
  • AriaMenuMixin. Renders state.selectedIndex as various ARIA attributes like aria-checked.
  • ArrowDirectionMixin. Renders left/right arrow buttons.
  • ContentItemsMixin. Defines an items property based on state.content, filtering out auxiliary invisible elements. During rendering, the component is given a chance to indicate what updates should be assigned to each specific item in items.
  • DelegateItemsMixin. Lets the items of a shadow element serve as the items of the component itself.
  • DialogModalityMixin. Renders a default ARIA role.
  • OverlayMixin. Renders an open state as changes to display and z-index to make an element appear on top.

Mixin that render updates to the DOM (updates → render DOM)

  • ReactiveMixin. Manages a component's state property, and renders the compnent when state changes.

Mixins that perform work after render

In rare cases, a mixin may need to perform work after a component has been rendered in the DOM.

Core mixins for reactive elements

For convenience, the following core mixins are provided in a base class called ReactiveElement.

  • AttributeMarshallingMixin. Maps attributes to properties.
  • ReactiveMixin. Manages a component's state property, and renders the compnent when state changes.
  • ShadowTemplateMixin. Creates a component's shadow root and stamps a template into it.
  • RenderUpdatesMixin. Helps a component map state to a set of updates that should be applied to DOM attributes, classes, styles, and properties.

All Elix components derive from ReactiveElement. However, when creating your own components, you don't have to use that base class; you can use the mixins above directly.

Other resources

More information and background about the Elix project can be found at the following: