Edit this page

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

Returns the first fragment matching the given 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 vicinity of a given { origin } element (optional).
  • This function supports non-standard CSS selectors like :main and :has().

If no element matches these conditions, undefined is returned.

Example: 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' })

Example: 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')

Example: Matching around an origin element

When processing a user interaction, it is often helpful to match elements around the link that's being clicked or 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.

Example: 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

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

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.

Parameters

[root=document] ElementorjQuery optional

The root element for the search. Only the root's children will be matched.

May be omitted to search through all elements in the document.

selector string

The selector to match.

[options.layer='current'] string optional

The layer in which to select elements.

See up.layer.get() for a list of supported layer values.

If a root element was passed as first argument, this option is ignored and the root element's layer is searched.

[options.origin] stringorElementorjQuery optional

An second element or selector that can be referenced as & in the first selector.

Return value

The first matching element, or undefined if no such element matched.

This website uses cookies to improve usability and analyze traffic.
I accept or learn more