up.fragment up.fragment.get([root], selector, [options])

JavaScript function

Returns the first fragment matching the given CSS selector.

This function differs from document.querySelector() and up.element.get():

• This function only selects elements in the current layer. Pass a { layer }option to match elements in other layers.
• This function ignores elements that are being destroyed or that are being removed by a transition.
• This function prefers to match elements in the region of a given { origin } element (optional).
• This function supports non-standard CSS extensions like :main and :has().

If no element matches these conditions, undefined is returned.

Matching a selector in a layer

To select the first element with the selector .foo on the current layer:

let foo = up.fragment.get('.foo')

You may also pass a { layer } option to match elements within another layer:

let foo = up.fragment.get('.foo', { layer: 'any' })

Matching the descendant of an element

To only select in the descendants of an element, pass a root element as the first argument:

let container = up.fragment.get('.container')
let fooInContainer = up.fragment.get(container, '.foo')

Matching in the origin's region

When processing a user interaction, it is often helpful to match elements in the region of the link that's being clicked or of the form field that's being changed. In this case you may pass the triggering element as { origin } element.

Assume the following HTML:

<div class="element">
</div>
<div class="element">
  <a href="..."></a>
</div>

When processing an event for the <a href"..."> you can pass the link element as { origin } to match the closest element in the link's ancestry:

let link = event.target
up.fragment.get('.element') // returns the first .element
up.fragment.get('.element', { origin: link }) // returns the second .element

When the link's does not have an ancestor matching .element, Unpoly will search the entire layer for .element.

To disable region-aware fragment matching, pass a { match: 'first' } option:

up.fragment.get('.element', { origin: link, match: 'first' })

Matching an origin sibling

When processing a user interaction, it is often helpful to match elements within the same container as the the link that's being clicked or the form field that's being changed.

Assume the following HTML:

<div class="element" id="one">
  <div class="inner"></div>
</div>
<div class="element" id="two">
  <a href="..."></a>
  <div class="inner"></div>
</div>

When processing an event for the <a href"..."> you can pass the link element as { origin } to match within the link's container:

let link = event.target
up.fragment.get('.element .inner') // returns the first .inner
up.fragment.get('.element .inner', { origin: link }) // returns the second .inner

Only when the link's .element container does not have a child .inner, Unpoly will search the entire layer for .element .inner.

Elements are returned unchanged

Passing an existing element will return it unchanged:

let element = document.querySelector(...)
up.fragment.get(element) // returns the given element

Similar features

• The .up-destroying class is assigned to elements during their removal animation.
• The up.element.get() function simply returns the first element matching a selector without filtering by layer or destruction state.