Understanding the jQuery prevUntil() Method

This article explains the purpose, syntax, and practical application of the jQuery prevUntil() method. You will learn how this DOM traversal function works, how it differs from similar sibling-traversal methods, and how to effectively use it to select a specific range of preceding sibling elements in an HTML document.

The Purpose of jQuery prevUntil()

The primary purpose of the prevUntil() method is to traverse backward along an element's preceding siblings in the DOM tree, returning all sibling elements up to—but not including—a specified stopping point.

When working with dynamic web pages, you frequently need to select a group of elements based on their relative position. While prev() selects only the single immediately preceding sibling, and prevAll() selects every preceding sibling all the way to the start of the parent container, prevUntil() provides a bounded range. It allows developers to target a precise subset of previous siblings located between the initial element and a defined boundary element.

Syntax and Parameters

The standard syntax for the prevUntil() method is:

$(selector).prevUntil(stop, filter);

The method accepts two optional parameters:

  1. stop (optional): A selector expression, DOM element, or jQuery object that defines where the backward search should stop. The search stops immediately when this boundary element is encountered, and the boundary element itself is excluded from the returned collection. If this parameter is omitted or cannot be found among the siblings, the method behaves like prevAll() and selects all preceding siblings.
  2. filter (optional): A secondary selector expression used to narrow down the selected siblings within the specified range. If an element falls within the range but does not match this filter, it is excluded from the final result.

Practical Example

Consider the following HTML list:

<ul>
  <li id="step-1">Step 1</li>
  <li id="step-2" class="completed">Step 2</li>
  <li id="step-3" class="completed">Step 3</li>
  <li id="step-4">Step 4</li>
  <li id="step-5">Step 5</li>
</ul>

If you want to select the completed steps between step-4 and step-1, you can execute:

$("#step-4").prevUntil("#step-1", ".completed").css("color", "green");

In this execution:

  • The traversal starts at #step-4 (excluded).
  • It looks backward toward #step-1 (excluded).
  • The intermediate siblings encountered are #step-3 and #step-2.
  • The .completed filter ensures only elements matching that class receive the green styling.

Common Use Cases

The prevUntil() method is particularly useful in user interfaces requiring sequential manipulation, such as:

  • Progress Trackers and Wizards: Highlighting or marking all previous steps as complete up to the initial step or a specific milestone.
  • Star Rating Widgets: Highlighting all rating stars before the hovered star up to a designated threshold.
  • Data Tables and Lists: Selecting a range of rows or list items above a clicked element without affecting the entire table or document.