jQuery API

.submit()

Categories: Events > Form Events | Forms

.submit( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "submit" JavaScript event, or trigger that event on an element.

  • version added: 1.0.submit( handler(eventObject) )

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

  • version added: 1.0.submit()

This method is a shortcut for .bind('submit', handler) in the first variation, and .trigger('submit') in the second.

The submit event is sent to an element when the user is attempting to submit a form. It can only be attached to <form> elements. Forms can be submitted either by clicking an explicit <input type="submit">, <input type="image">, or <button type="submit">, or by pressing Enter when certain form element has focus.

Depending on the browser, the Enter key may only cause a form submission if the form has exactly one text field, or only when there is a submit button present. The interface should not rely on a particular behavior for this key unless the issue is forced by observing the keypress event for presses of the Enter key.

For example, consider the HTML:

<form id="target" action="destination.html">
  <input type="text" value="Hello there" />
  <input type="submit" value="Go" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the form:

$('#target').submit(function() {
  alert('Handler for .submit() called.');
  return false;
});

Now when the form is submitted, the message is alerted. This happens prior to the actual submission, so we can cancel the submit action by calling .preventDefault() on the event object or by returning false from our handler. We can trigger the event manually when another element is clicked:

$('#other').click(function() {
  $('#target').submit();
});

After this code executes, clicks on Trigger the handler will also display the message. In addition, the default submit action on the form will be fired, so the form will be submitted.

The JavaScript submit event does not bubble in Internet Explorer. However, scripts that rely on event delegation with the submit event will work consistently across browsers as of jQuery 1.4, which has normalized the event's behavior.

Examples:

Example: If you'd like to prevent forms from being submitted unless a flag variable is set, try: 

<!DOCTYPE html>
<html>
<head>
  <style>

  p { margin:0; color:blue; }
  div,p { margin-left:10px; }
  span { color:red; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Type 'correct' to validate.</p>
  <form action="javascript:alert('success!');">
    <div>
      <input type="text" />

      <input type="submit" />
    </div>
  </form>
  <span></span>
<script>

    $("form").submit(function() {
      if ($("input:first").val() == "correct") {
        $("span").text("Validated...").show();
        return true;
      }
      $("span").text("Not valid!").show().fadeOut(1000);
      return false;
    });
</script>
</body>
</html>

Demo:

Example: If you'd like to prevent forms from being submitted unless a flag variable is set, try: 

$("form").submit( function () {
  return this.some_flag_variable;
} );

Example: To trigger the submit event on the first form on the page, try: 

$("form:first").submit();

Comments

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

  • Please do post corrections or additional examples for .submit() 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.
  • jude
    How to change the action on change of the select box in jquery

    $(document).ready(function(){
    $('#site_id').change(function(){
    document.site.action = "/admin/login/change_website"
    document.site.submit();
    });
    });
  • You can stop the form from being submitted with either return false or preventDefault(), however, it should be noted that if you have a JavaScript error in your function, the form will submit regardless.
  • warrentucker
    The best way i have got round this is to use the target attribute and force the form in an iframe this works very well also if you use the dialog plugin in the ui section this has an added effect.
  • Ian
    Why doesn't this event handler work with multipart forms?
  • Ian
    Ok, got it working.

    It was hard to get my head around it working with the DOM and then what has been posted / reset and if the event handler could find the object in the DOM.

    Basically, I put this event handler on a link but also included a submit input type in the form as well. (some browsers wont submit the form without one).

    Now you don't want the submit button and the link to show at the same time. So what I have done is just simply hide the submit button with CSS.

    Now I can bind any event on the link and then submit the form, for example I can place an uploading message in the DOM and then submit the form so users know that they need to wait a little while.

    Cheers.
  • Yeah I'm having this problem too =(
    I have a "file" input field in my form and the file isn't going through.
  • JqueryNewbie
    me too. Does any one of you get this working?
  • downeywebdevelopment
    If you don't know the form id, but you know the elements you can grab the form then hook it's submit function to do some additional processing:
    $(document.getElementById('elementId').form).submit(function() {
    // form processing
    return true;
    });
  • jamesfurey
    @scotty I too was failing silently with <input type="button" name="submit" id="submit">... changed the 'id' and 'name', and works fine now.
  • An alternate workaround exists (if you can't rename it):

    $form.find('input[name=submit]').click();

    Something really should be added to the source to detect this strange case...