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.
  • Taliesin
    What about when you have a list of toggle blocks? Is there a way to close/hide a toggled block if one is already open, before opening the new toggled block.

    My blocks all appear in the same place, and so they stack on top of each other. I would just like the one that's open to close as/before the next one opens.
    //Get doc ready
    $(document).ready(function() {
    //Click on the inside a parent with the toggle class.
    $(".toggle a").click(function() {
    //Toggle the sibling which is marked with the class answer.
    $(this).next(".toggle .answer").slideToggle(600);
    });
    });

    How do I check for an open toggle?
  • 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().
  • 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>