jQuery API

.toggle()

Categories: Effects > Basics | Events > Mouse Events
Contents:

.toggle( handler(eventObject), handler(eventObject), [ handler(eventObject) ] ) Returns: jQuery

Description: Bind two or more handlers to the matched elements, to be executed on alternate clicks.

  • version added: 1.0.toggle( handler(eventObject), handler(eventObject), [ handler(eventObject) ] )

    handler(eventObject)A function to execute every even time the element is clicked.

    handler(eventObject)A function to execute every odd time the element is clicked.

    handler(eventObject)Additional handlers to cycle through after clicks.

The .toggle() method binds a handler for the click event, so the rules outlined for the triggering of click apply here as well.

For example, consider the HTML:
<div id="target">
  Click here
</div>

Event handlers can then be bound to the <div>:

$('#target').toggle(function() {
  alert('First handler for .toggle() called.');
}, function() {
  alert('Second handler for .toggle() called.');
});

As the element is clicked repeatedly, the messages alternate:

First handler for .toggle() called.
Second handler for .toggle() called.
First handler for .toggle() called.
Second handler for .toggle() called.
First handler for .toggle() called.

If more than two handlers are provided, .toggle() will cycle among all of them. For example, if there are three handlers, then the first handler will be called on the first click, the fourth click, the seventh click, and so on.

The .toggle() method is provided for convenience. It is relatively straightforward to implement the same behavior by hand, and this can be necessary if the assumptions built into .toggle() prove limiting. For example, .toggle() is not guaranteed to work correctly if applied twice to the same element. Since .toggle() internally uses a click handler to do its work, we must unbind click to remove a behavior attached with .toggle(), so other click handlers can be caught in the crossfire. The implementation also calls .preventDefault() on the event, so links will not be followed and buttons will not be clicked if .toggle() has been called on the element.

Examples:

Example: Click to toggle highlight on the list item. 

<!DOCTYPE html>
<html>
<head>
  <style>
  ul { margin:10px; list-style:inside circle; font-weight:bold; }
  li { cursor:pointer; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<ul>
    <li>Go to the store</li>
    <li>Pick up dinner</li>
    <li>Debug crash</li>

    <li>Take a jog</li>
  </ul>
<script>
    $("li").toggle(
      function () {
        $(this).css({"list-style-type":"disc", "color":"blue"});
      },
      function () {
        $(this).css({"list-style-type":"disc", "color":"red"});
      },
      function () {
        $(this).css({"list-style-type":"", "color":""});
      }
    );

</script>
</body>
</html>

Demo:

Example: To toggle a style on table cells: 

$("td").toggle(
  function () {
    $(this).addClass("selected");
  },
  function () {
    $(this).removeClass("selected");
  }
);

.toggle( [ duration ], [ callback ] ) Returns: jQuery

Description: Display or hide the matched elements.

  • version added: 1.0.toggle( [ duration ], [ callback ] )

    durationA string or number determining how long the animation will run.

    callbackA function to call once the animation is complete.

  • version added: 1.3.toggle( showOrHide )

    showOrHideA Boolean indicating whether to show or hide the elements.

Examples:

Example: Toggles all paragraphs. 

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<button>Toggle</button>
<p>Hello</p>
<p style="display: none">Good Bye</p>
<script>

$("button").click(function () {
$("p").toggle();
});
</script>
</body>
</html>

Demo:

Example: Animates all paragraphs to be shown if they are hidden and hidden if they are visible, completing the animation within 600 milliseconds. 

<!DOCTYPE html>
<html>
<head>
  <style>
p { background:#dad;
font-weight:bold;
font-size:16px; }
</style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<button>Toggle 'em</button>

<p>Hiya</p>
<p>Such interesting text, eh?</p>
<script>
$("button").click(function () {
$("p").toggle("slow");
});    
</script>
</body>
</html>

Demo:

Example: Shows all paragraphs, then hides them all, back and forth. 

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<button>Toggle</button>
<p>Hello</p>
<p style="display: none">Good Bye</p>
<script>

var flip = 0;
$("button").click(function () {
$("p").toggle( flip++ % 2 == 0 );
});
</script>
</body>
</html>

Demo:

Comments

  • Support requests, bug reports, and off-topic comments will be deleted without warning.

  • Please do post corrections or additional examples for .toggle() below. We aim to quickly move corrections into the documentation.
  • If you need help, post at the forums or in the #jquery IRC channel.
  • Report bugs on the bug tracker or the jQuery Forum.
  • Discussions about the API specifically should be addressed in the Developing jQuery Core forum.
  • Greg
    There are issues with toggle in IE8 table rows. See: http://www.code-styling.de/english/jquery-132-c...
  • Joe
    Is there a good way to trigger a toggle() on an element from another element, or more specifically, only one side of the toggle functions. For instance, I want a toggle() show/hide, but I also want another element to simply trigger the hide side of the toggle().
  • I don't completely get what you're asking... but I suspect it would be helpful to know that if you call .toggle(true) it will only show an object and likewise .toggle(false) will only hide it.
  • Joe
    The toggle seems to track the last action , either a show or hide, not based on whether or not the element is showing or hidden. This is probably because a toggle can begin in either state. So here's an example. You show an element via clicking in it (fires a toggle). Now, you have another element that when clicked, will hide the original element that was shown with the toggle. When you return to the toggle to show the element via toggle, you will have to click it twice before the toggle "catches up".

    Is there any function that can invoke a "click" on the original toggle, instead of hiding it manually and throwing off the toggle tracking.
  • Ben
    There is a simple solution. Just do .click() on the element with the toggle:

    $('.slidetrigger').toggle(...);
    $('.opencloseall').click(function() { $('.slidetrigger').click(); });
  • Hi Joe,

    I have the same problem. Please tell me if you found a solution to your problem. Thanks.
  • I see what you're saying now.. but I can't really recreate it. I made an element that would fire toggle when clicked, then I clicked it (to show it) and went into firebug and changed the display back to 'none'... however when I clicked it again it showed after just one click. I'm using jQuery 1.4.1

    But that being said, in your example, when you have the 'other element' hide it, why can't you just use the jQuery selector and toggle it? (ie $("#otherElement").click(function() { $("#hideshowElement").toggle() }); )
  • mubarak
    Hi Joe,

    I am need of script, the same what you need, SHOW/Hide so if you find solution for that, please give me a mail.
  • arabicman
    You can easily show/hide a div by using this small function:

    function toggle_div(target_div){
    $('#'+target_div).toggle("slow");
    }

    You can call it from a link for example like this:

    <a href="javascript:void();" onclick="toggle_div('test')">Show/Hide

    based on the following test div having id="test", if you change the div id you should change it in the link as well

    <div id="test"></div>