Miscellaneous utility functions for web components


deepContains(container, target) static method

Returns true if the first node contains the second, even if the second node is in a shadow tree.

The standard Node.contains() function does not account for Shadow DOM, and returns false if the supplied target node is sitting inside a shadow tree within the container.


  • container: NodeThe container to search within.
  • target: NodeThe node that may be inside the container.

Returns: boolean - True if the container contains the target node.

defaultFocus(element) static method

Determine which shadow or child element the indicated element would like to treat as the default element to focus on.

This proceeds by starting with the indicated element, seeing whether it defines another element as the one which should receive the focus, and repeating that process.

OverlayMixin uses this utility to determine where the focus should be put when an overlay is opened.


  • element: HTMLElement

Returns: HTMLElement

elementsFromPoint(element, x, y) static method

Polyfill for shadowRoot.elementsFromPoint, which (as of 6 June 2018) is not available in the webcomponents polyfill. See https://github.com/webcomponents/shadydom/issues/141.


  • element: Elementelement whose shadow root may contain elements at the specified point
  • x: numberx-coordinate of the indicated point
  • y: numbery-coordinate of the indicated point

Returns: Array.

forwardFocus(origin, target) static method

TODO: Docs


  • origin: HTMLElement
  • target: HTMLElement|null

indexOfItemContainingTarget(listElement, target) static method

Search a list element for the item that contains the specified target.

When dealing with UI events (e.g., mouse clicks) that may occur in subelements inside a list item, you can use this routine to obtain the containing list item.


  • listElement: NodeA list element containing a set of items
  • target: NodeA target element that may or may not be an item in the list.

Returns: number - The index of the list child that is or contains the indicated target node. Returns -1 if not found.

ownEvent(node, event) static method

Return true if the event came from within the node (or from the node itself); false otherwise.


  • node: NodeThe node to consider in relation to the event
  • event: EventThe event which may have been raised within/by the node

Returns: boolean - True if the event was raised within or by the node

stateChanged(newState, oldState) static method

Compare a new state object against an older state object and:

  1. Destructively update the old state so that its field values match those of the corresponding fields in the newer state. (Fields in the new state that are not present in the old state are skipped.)
  2. Return a set of flags indicating which old state fields had to be changed to match the new state.

E.g., suppose the old state contains

{ a: 1, b: 'Hello' }

and the new state contains

{ a: 1, b: 'Goodbye', c: true }

This function updates the old state to

{ a: 1, b: 'Goodbye' }

and returns the flags

{ a: false, b: true }

Because field a did not change, but field b did.

This function is used by refineState functions that are interested in seeing whether specific state fields have changed since the last call to refineState.


  • newState: object
  • oldState: object

Returns: object - flags for the state fields that changed