jQuery .one() Method

What You’ll Learn

The .one() method attaches event handlers that run at most once per element per event type, then automatically unbind. It mirrors .on() in every signature — direct binding, delegation, eventData, and event maps — but saves you from manually calling .off(event) inside the handler.

Introduction

Most event handlers should keep listening — every button click saves a form, every keystroke filters a list. But sometimes you only need a handler to fire once: a welcome tooltip on first hover, a one-time confirmation, or an initialization step triggered by the user’s first interaction.

jQuery’s .one() method (available since 1.1, with delegation added in 1.7) attaches a handler and removes it automatically after the first invocation on each matched element. It is the concise alternative to writing .on() followed by $(this).off(event) inside the callback.

Understanding .one()

When you call $("#foo").one("click", handler), jQuery registers the handler exactly like .on(). The difference appears after the first click on #foo: jQuery detaches that handler. A second click does nothing unless you bind again.

If you bind .one("click mouseenter", fn) with two event types, the handler can run up to twice on the same element — once for the first click and once for the first mouseenter. The limit is once per event type per element, not once total.

📝 Syntax

Three signatures from the official jQuery API:

1. Direct binding — .one( events [, data ], handler ) since 1.1

.one( events [, data ], handler )

2. With delegation — .one( events [, selector ] [, data ], handler ) since 1.7

$( "#list" ).one( "click", "li", function() {
  alert( "First click on this li only!" );
} );

3. Events map — .one( events [, selector ] [, data ] ) since 1.7

$( "div" ).one({
  click: function() { /* runs once */ },
  mouseenter: function() { /* runs once per type */ }
});

Equivalent manual pattern

// .one() shorthand
$( "#foo" ).one( "click", function() {
  alert( "This will be displayed only once." );
});

// Explicit .on() + .off(event) — same effect
$( "#foo" ).on( "click", function( event ) {
  alert( "This will be displayed only once." );
  $( this ).off( event );
});

Return value

• Returns the original jQuery object for chaining.
• Accepts false as handler shorthand (same as .on()).

Examples Gallery

All five examples follow the official jQuery API documentation for .one(). Try clicking repeatedly to see handlers fire only once per element or event type.

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

First click on #foo → alert appears

Second click → nothing (handler removed)

Same as .on("click", fn) + $(this).off(event)

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." );
});

Click square 0 → "Div at index #0 clicked. That's 1 total clicks."

Click square 1 → counter increments; square 0 ignores further clicks

Each div: one handler, one response

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

First click on any p → alert with its text

Second click on same p → no alert

Different paragraphs each get one alert

var n = 0;

$( ".target" ).one( "click mouseenter", function( event ) {
  $( ".count" ).html( ++n );
  alert( "The " + event.type + " event happened!" );
});

First mouseenter → alert "The mouseenter event happened!" count=1

First click → alert "The click event happened!" count=2

Second mouseenter or click → nothing

$( "#list" ).one( "click", "li", function() {
  $( this ).addClass( "visited" ).text( "Visited once: " + $( this ).text() );
});

// New items added later still get one click each
$( "#add" ).on( "click", function() {
  $( "#list" ).append( "
New item
" );
});

Click li → "visited" styling, text updated once

Click same li again → no change

Add new li via button → first click works, second ignored

🚀 Common Use Cases

• First-click tutorials — show a hint the first time a user clicks a feature button.
• One-time confirmations — “Are you sure?” dialog bound with .one("click", confirmFn).
• Lazy initialization — load heavy resources on first user interaction instead of page load.
• Mark-as-read — delegated .one("click", "li", markRead) on notification lists.
• Intro animations — play a welcome animation once per section on first scroll or hover.
• Replacing manual cleanup — swap .on() + .off(event) for readable .one().

📝 Notes

• .one() has existed since jQuery 1.1; delegation support arrived in 1.7 alongside .on().
• Space-separated event types mean once per type, not once total — .one("click mouseenter", fn) can run twice on the same element.
• Explicitly calling .off() from within a regularly-bound handler has the same effect as using .one() for a single type.
• Delegated .one() does not work for SVG elements (same limitation as .on() delegation).
• Non-bubbling events (scroll, load, error on some elements) cannot use delegation with .one() either.
• To re-enable after the one shot, call .one() or .on() again in your handler or elsewhere.

💡 Best Practices