jQuery API

.one()

Categories: Events > Event Handler Attachment

.one( events [, data] , handler(eventObject) ) Returns: jQuery

Description: Attach a handler to an event for the elements. The handler is executed at most once per element.

  • version added: 1.1.one( events [, data], handler(eventObject) )

    eventsA string containing one or more JavaScript event types, such as "click" or "submit," or custom event names.

    dataA map of data that will be passed to the event handler.

    handler(eventObject)A function to execute at the time the event is triggered.

  • version added: 1.7.one( events [, selector] [, data], handler(eventObject) )

    eventsOne or more space-separated event types and optional namespaces, such as "click" or "keydown.myPlugin".

    selectorA selector string to filter the descendants of the selected elements that trigger the event. If the selector is null or omitted, the event is always triggered when it reaches the selected element.

    dataData to be passed to the handler in event.data when an event is triggered.

    handler(eventObject)A function to execute when the event is triggered. The value false is also allowed as a shorthand for a function that simply does return false.

  • version added: 1.7.one( events-map [, selector] [, data] )

    events-mapA map in which the string keys represent one or more space-separated event types and optional namespaces, and the values represent a handler function to be called for the event(s).

    selectorA selector string to filter the descendants of the selected elements that will call the handler. If the selector is null or omitted, the handler is always called when it reaches the selected element.

    dataData to be passed to the handler in event.data when an event occurs.

The first form of this method is identical to .bind(), except that the handler is unbound after its first invocation. The second two forms, introduced in jQuery 1.7, are identical to .on() except that the handler is removed after the first time a selector match occurs at the delegated element. For example:

$("#foo").one("click", function() {
  alert("This will be displayed only once.");
});
$("body").one("click", ".foo", function() {
  alert("This displays once for the first .foo clicked in the body.");
});

After the code is executed, a click on the element with ID foo will display the alert. Subsequent clicks will do nothing. This code is equivalent to:

$("#foo").bind("click", function( event ) {
  alert("This will be displayed only once.");
  $(this).unbind( event );
});

In other words, explicitly calling .unbind() from within a regularly-bound handler has exactly the same effect.

If the first argument contains more than one space-separated event types, the event handler is called once for each event type.

Examples:

Example: Tie a one-time click to each div. 

<!DOCTYPE html>
<html>
<head>
  <style>
div { width:60px; height:60px; margin:5px; float:left;
background:green; border:10px outset; 
cursor:pointer; }
p { color:red; margin:0; clear:left; }
</style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
  
<div></div>
<div></div>
<div></div>
<div></div>
<div></div>

<p>Click a green square...</p>

<script>
var n = 0;
$("div").one("click", function() {
  var index = $("div").index(this);
  $(this).css({ 
    borderStyle:"inset",
    cursor:"auto"
  });
  $("p").text("Div at index #" + index + " clicked." +
      "  That's " + ++n + " total clicks.");
});

</script>

</body>
</html>

Demo:

Example: To display the text of all paragraphs in an alert box the first time each of them is clicked: 

$("p").one("click", function(){
alert( $(this).text() );
});

Support and Contributions

Need help with .one() or have a question about it? Visit the jQuery Forum or the #jquery channel on irc.freenode.net.

Think you've discovered a jQuery bug related to .one()? Report it to the jQuery core team.

Found a problem with this documentation? Report it on the GitHub issue tracker

  • bkrausz

    Note: you cannot unbind a listener created using .one(). If you want to be able to unbind something that has to occur only once but still be able to unbind it before it occurs, use the example provided for unbinding an event after it's called, and bind it using .bind().

    • tim_atom

      Assuming one is the only bound click, its very easy to unbind. A less-than-jQuery approach could be: delete $().data(“events”).click

      • Patrickgamer

        …but that will disable everything under click, right? This is not idea (as far as I know) for multiple handlers bound to the click if only one of those handlers are to be ran once. Am I mistaken about this?

        • Patrickgamer

          *not ideal

  • adardesign

    Thanks for the wonderfull api
    I am trying:
    $(document).bind(“click”, function(e){
    if(!$(e.target).hasClass(“open”) && !$(e.target).hasClass(“cont”)){
    $(“.drop”).slideUp(500).parent().removeClass(“open”)
    }
    })

    But it doesn't work unless i use .bind() instead of .one()
    Any idea why

  • hoerf

    is it possible to reset the one function?
    i wanna reset it in a spacial case/event.

    • http://www.fiesto.com Junaidi Kurniawan

      If you want to make it cannot be clicked before the animation finished, do not use “one”. Use “bind”, then run your codes only if the element is not animated.

      if (!$('#divname').is(':animated')) {
      (your code here)
      }

      Hope this helps.

  • http://www.fiesto.com Junaidi Kurniawan

    If you want to make it cannot be clicked before the animation finished, do not use “one”. Use “bind”, then run your codes only if the element is not animated.

    if (!$('#divname').is(':animated')) {
    (your code here)
    }

    Hope this helps.