src code

class method Element.previous

Element.previous(element[, expression[, index = 0]]) → Element
Element.previous(element[, index = 0]) → Element
  • expression (String) – A CSS selector.

Returns element's first previous sibling (or the Nth, if index is specified) that matches expression. If no expression is provided, all previous siblings are considered. If none matches these criteria, undefined is returned.

More information

The Element.previous method is part of Prototype's ultimate DOM traversal toolkit (check out Element.up, Element.down and Element.next for some more Prototypish niceness). It allows precise index-based and/or CSS expression-based selection of any of element's previous siblings. (Note that two elements are considered siblings if they have the same parent, so for example, the head and body elements are siblings—their parent is the html element.)

As it totally ignores text nodes (it only returns elements), you don't have to worry about whitespace nodes.

And as an added bonus, all elements returned are already extended (see Element.extend) allowing chaining:

$(element).down('p').previous('ul', 2).hide();

Walking the DOM has never been that easy!

Arguments

If no arguments are passed, element's previous sibling is returned (this is similar as calling previousSibling except Element.previous returns an already extended element).

If index is defined, element's corresponding previous sibling is returned. (This is equivalent to selecting an element from the array of elements returned by the method Element.previousSiblings). Note that the sibling right above element has an index of 0.

If expression is defined, Element.previous will return the element first previous sibling that matches it.

If both expression and index are defined, Element.previous will collect all of element's previous siblings matching the given CSS expression and will return the one at the specified index.

In all of the above cases, if no previous sibling is found, undefined will be returned.

Examples
<ul id="fruits">
  <li id="apples">
    <h3>Apples</h3>
    <ul id="list-of-apples">
      <li id="golden-delicious" class="yummy">Golden Delicious</li>
      <li id="mutsu" class="yummy">Mutsu</li>
      <li id="mcintosh">McIntosh</li>
      <li id="ida-red">Ida Red</li>
    </ul>
    <p id="saying">An apple a day keeps the doctor away.</p>
  </li>
</ul>

Get the first previous sibling of "#saying":

$('saying').previous();
// or:
$('saying').previous(0);
// -> ul#list-of-apples

Get the second previous sibling of "#saying":

$('saying').previous(1);
// -> h3

Get the first previous sibling of "#saying" with node name "h3":

$('saying').previous('h3');
// -> h3

Get the first previous sibling of "#ida-red" with class name "yummy":

$('ida-red').previous('.yummy');
// -> li#mutsu

Get the second previous sibling of "#ida-red" with class name "yummy":

$('ida-red').previous('.yummy', 1);
// -> li#golden-delicious

Try to get the sixth previous sibling of "#ida-red":

$('ida-red').previous(5);
// -> undefined

This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.