INPUT - Form Input

<INPUT>

TYPE=[ text | password | checkbox | radio | submit | reset | file | hidden | image | button ] (type of input)
NAME=CDATA (key in submitted form)
VALUE=CDATA (value of input)
CHECKED (check radio button or checkbox)
SIZE=CDATA (suggested number of characters for text input)
MAXLENGTH=Number (maximum number of characters for text input)
SRC=url (source for image)
ALT=CDATA (alternate text for image input)
USEMAP=url (client-side image map)
ALIGN=[ top | middle | bottom | left | right ] (alignment of image input)
DISABLED (disable element)
READONLY (prevent changes)
ACCEPT=ContentTypes (media types for file upload)
ACCESSKEY=Character (shortcut key)
TABINDEX=Number (position in tabbing order)
ID=string
CLASS=string
STYLE=string
TITLE=string
LANG=Language (i.e. RU - Russian)
DIR=ltr|rtl
SCRIPTING EVENTS=string
ONFOCUS=Script (element received focus)
ONBLUR=Script (element lost focus)
ONSELECT=Script (element text selected)
ONCHANGE=Script (element value changed)

Empty

Block-level elements, inline elements except BUTTON

The INPUT element defines a form control for the user to enter input. While INPUT is most useful within a FORM, HTML 4.0 allows INPUT in any block-level or inline element other than BUTTON. However, Netscape Navigator will not display any INPUT elements outside of a FORM.

When a form is submitted, the current value of each INPUT element within the FORM is sent to the server as name/value pairs. The INPUT element's NAME attribute provides the name used. The value sent depends on the type of form control and on the user's input.

The type of form control defined by INPUT is given by the TYPE attribute. The default TYPE is text, which provides a single-line text input field. The VALUE attribute specifies the initial value for the text field. The SIZE and MAXLENGTH attributes suggest the number of characters and maximum number of characters, respectively, of the text field.

While the MAXLENGTH attribute can be an effective guide to the user, authors should not depend on the enforcement of a maximum number of characters by the client. A user could copy the HTML document, remove the MAXLENGTH attribute, and submit the form. Thus authors of form handlers should ensure that any necessary input length checks are repeated on the server-side.

The password input type is a variation on the text type. The only difference is that the input characters are masked, typically by a series of asterisks, to protect sensitive information from onlookers. Note, however, that the actual value is transmitted to the server as clear text, so password inputs do not provide sufficient securlty for credit card numbers or other highly sensitive information.

The following example uses text and password fields with the LABEL element to bind text labels to the INPUT elements:

<P><LABEL ACCESSKEY=U>User name: <INPUT TYPE=text NAME=username SIZE=8 MAXLENGTH=8></LABEL></P>
<P><LABEL ACCESSKEY=P>Password: <INPUT TYPE=password NAME=pw SIZE=12 MAXLENGTH=12></LABEL></P>

The boolean READONLY attribute, new in HTML 4.0 and poorly supported by current browsers, prevents the user from editing the content of the text or password input types. Read-only elements are still submitted with the form. The DISABLED attribute, which applies to all input types but is also poorly supported, disables the control. Disabled elements are read-only elements with the added restrictions that the values are not submitted with the form, the elements cannot receive focus, and the elements are skipped when navigating the document by tabbing.

The radio and checkbox input types provide switches that can be turned on and off by the user. The two types differ in that radio buttons are grouped (by specifying the same NAME attribute on each INPUT) so that only one radio button in a group can be selected at any time. Checkboxes can be checked without changing the state of other checkboxes with the same NAME. The VALUE attribute, required for radio buttons and checkboxes, gives the value of the control when it is checked. The boolean CHECKED attribute specifies that the control is initially checked.

Some browsers require one radio button in a group to be selected at all times. To ensure that an appropriate default choice is made, authors may wish to define one of the radio INPUT elements as CHECKED.

In the following example, only one payment method may be selected by the user since the radio buttons have the same NAME:

The file input type creates a field through which users can upload files from their local computer or network. The VALUE attribute specifies the name of the initial file, but it is typically ignored by browsers as a securlty precaution. The ACCEPT attribute gives a comma-separated list of media types accepted, allowing the browser to filter out inappropriate files. Current browsers generally ignore the ACCEPT attribute.

A form that includes a file INPUT must specify METHOD=post and ENCTYPE="multipart/form-data" in the <FORM> tag. CGI libraries such as CGI.pm allow simple handling of such forms.

Form-based file upload is unsupported by many currently deployed browsers. Authors should provide alternative methods of input where possible.

The following example allows the user to upload an HTML document for validation:

<FORM METHOD=post ACTION="/cgi-bin/validate.cgi" ENCTYPE="multipart/form-data">
<P>Select an HTML document to upload and validate. If your browser does not support form-based file upload, use one of our <A HREF="methods.html">alternate methods of validation</A>.</P>
<P><INPUT TYPE=file NAME="html_file" ACCEPT="text/html"></P>
<P><INPUT TYPE=submit VALUE="Validate it!"></P>
</FORM>

The hidden input type allows authors to include form data without having it rendered to the user. This is particularly useful in form applications that span several HTML documents; user input can be carried from form to form by hidden INPUTs. Some generalized CGI scripts use hidden INPUTs to define variables for the script, as in the following example, which defines a recipient and subject for the e-mailed contents of a form:

<INPUT TYPE=hidden NAME=recipient VALUE="liam@htmlhelp.com">
<INPUT TYPE=hidden NAME=subject VALUE="Feedback on your HTML Reference">

Note that the fields are "hidden" in the sense that they are not rendered by the browser. Anyone can still view the HTML document's source to find the "hidden" fields.

The TYPE value reset defines a button by which the user can reset the form to its initial values. The optional VALUE attribute of a reset button overrides the browser's default text for the button.

The submit input type defines a button for submitting the form. As with reset, the optional VALUE attribute provides the text of the button. The presence of the NAME attribute will cause the browser to send a name/value pair for the submit button if it is used to submit the form. This allows authors to provide multiple submit buttons and have the form handler take a different action depending on the submit button used.

The image input type specifies a graphical submit button. The SRC attribute must be included to specify the url of the image. The ALT attribute should be used to give replacement text for those not loading images. ALT is a new addition in HTML 4.0; many browsers rely on either the NAME or VALUE attribute as alternate text, so authors should use all three attributes for the same purpose where possible. The topic of graphical submit buttons for text users is discussed in detail in the article INPUT TYPE=IMAGE for text users?.

When the graphical submit button is clicked, the coordinates of the click are sent with the form submission as name.x=x-value and name.y=y-value where name is the value of the NAME attribute, x-value is the click's pixels from the left of the image, and y-value is the click's pixels from the top of the image. The USEMAP attribute combined with TYPE=image defines a client-side image map that can be used with client-side scripting, but this method is poorly supported. The USEMAP attribute gives the url of the defining MAP.

The input type button specifies a push button for use with client-side scripting. The VALUE attribute gives the text label of the button. The ONCLICK attribute is typically used to define the action taken when the button is activated. An example follows:

<INPUT TYPE=button VALUE="Hide non-strict attributes" ID=toggler ONCLICK="toggle()">

In this example, the toggle() function, which would be defined earlier in a SCRIPT element, will be executed when the button is clicked. Since the button is only useful with client-side scripting enabled, authors should usually output the <INPUT TYPE=button> tag using the scripting language to avoid providing a non-functioning button to some users. A more complete version of the previous example would thus be as follows:

<SCRIPT TYPE="text/javascript">
<!--
  document.write("<INPUT TYPE=button VALUE=\"Hide non-strict attributes\""
                 + "ID=toggler ONCLICK=\"toggle()\">");
// -->
</script>

The BUTTON element allows richer labels for submit, reset, and push buttons, but a lack of browser support makes INPUT a more reliable choice at this time.

The ACCESSKEY and TABINDEX attributes apply to all input types except hidden. ACCESSKEY specifies a single Unicode character as a shortcut key for giving focus to the form control. Authors can set the access key on the INPUT element or the LABEL element associated with it. Entities (e.g. &eacute;) may be used as the ACCESSKEY value.

The TABINDEX attribute specifies a number between 0 and 32767 to indicate the tabbing order of the element. A form control with TABINDEX=0 or no TABINDEX attribute will be visited after any elements with a positive TABINDEX. Among positive TABINDEX values, the lower number receives focus first. In the case of a tie, the element appearing first in the HTML document takes precedence.

The INPUT element also takes a number of attributes to specify client-side scripting actions for various events. In addition to the core events common to most elements, INPUT accepts the following event attributes:

• ONFOCUS, when the element receives focus;
• ONBLUR, when the element loses focus;
• ONSELECT, when text in an input of type text or password is selected;
• ONCHANGE, when the element loses focus and its value has changed since it received focus.

The ID attribute uniquely identifies an element within a document. No two elements can have the same ID value in a single document. The attribute's value must begin with a letter in the range A-Z or a-z and may be followed by letters (A-Za-z), digits (0-9), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").

The following example uses the ID attribute to identify each of the first two paragraphs of a document:

<P ID=firstp>My first paragraph.</P>
<P ID=second>My second paragaph.</P>

The paragraphs in the example could have style rules associated with them through their ID attributes. The following Cascading Style Sheet defines unique colors for the two paragraphs:

P#firstp {
  color: navy;
  background: transparent
}

P#secondp {
  color: black;
  background: transparent
}

The paragraphs in the initial example could also be used as a target anchor for links:

<P>See <A HREF="#firstp">the opening paragraph</A> for more information.</P>

The CLASS attribute specifies the element to be a member of one or more classes. Classes allow authors to define specific kinds of a given element. For example, an author could use <CODE CLASS=Java> when giving Java code and <CODE CLASS=Perl> when giving Perl code.

Unlike with the ID attribute, any number of elements can share the same class. An element may also belong to multiple classes; the CLASS attribute value is a space-separated list of class names.

Note that most current browsers do not support multiple classes. Such browsers typically ignore a CLASS attribute that specifies multiple classes.

The CLASS attribute is particularly useful when combined with style sheets. For example, consider the following navigation bar:

<DIV CLASS=navbar>
<P><A HREF="/">Home</A> | <A HREF="./">Index</A> | <A HREF="/search.html">Search</A></P>
<P><A HREF="/"><IMG SRC="logo.gif" ALT="" TITLE="WDG Logo"></A></P>
</DIV>

This example's use of the CLASS attribute allows style rules to easily be added. The following Cascading Style Sheet suggests a presentation for the preceding example:

.navbar {
  margin-top: 2em;
  padding-top: 1em;
  border-top: solid thin navy
}

.navbar IMG { float: right }

@media print {
  .navbar { display: none }
}

The STYLE attribute allows authors to specify style rules inline for a single occurrence of an element. An example follows:

<P>A popular font for on-screen reading is <SPAN STYLE="font-family: Verdana">Verdana</SPAN>.</P>

When the STYLE attribute is used, a default style sheet language must be specified for the document by setting the Content-Style-Type HTTP header to the media type of the style sheet language. The previous example could use the following META element in the document's HEAD:

<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

In most cases, use of the CLASS or ID attributes is a better choice than using STYLE since ID and CLASS can be selectively applied to different media and since they provide a separation of content and presentation that often simplifies maintenance.

The TITLE attribute provides a title for an element and is commonly implemented as a "tooltip" on visual browsers, though many browsers lack support for TITLE. The attribute is most useful with A, LINK, IMG, and OBJECT elements, where it provides a title for the linked or embedded resource. Some examples follow:

• <A HREF="mailto:liam@htmlhelp.com" TITLE="Feedback on HTML 4.0 Reference">liam@htmlhelp.com</A>
• <A HREF="http://www-genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html" TITLE="CGI.pm - a Perl5 CGI Library">CGI.pm</A>
• <LINK REL=Alternate HREF="index.fr.html" HREFLANG=fr LANG=fr TITLE="Version française">
• <OBJECT CLASSID="java:Yahtzee.class" CODETYPE="application/java" WIDTH=400 HEIGHT=250 STANDBY="Ready to play Yahtzee?" TITLE="My Yahtzee Game">
<IMG SRC="yahtzee.gif" ALT="" TITLE="A Yahtzee animation">
Yahtzee is my <EM>favorite</EM> game!
</OBJECT>

TITLE is also helpful with the ABBR and ACRONYM elements to provide the long form of the abbreviation. Examples:

• He weighs 180 <ABBR TITLE=pounds>lbs.</ABBR>
• <ABBR TITLE="Parti Québécois" LANG=fr-CA>PQ</ABBR>
• <ACRONYM TITLE="North Atlantic Treaty Organization">NATO</ACRONYM>

The LANG attribute specifies the language of an element's attribute values and its content, including all contained elements that do not specify their own LANG attribute. While the LANG attribute is not widely supported, its use may help search engines index a document by its language while allowing speech synthesizers to use language-dependent pronunciation rules. As well, visual browsers can use the language's proper quotation marks when rendering the Q element.

The attribute value is case-insensitive, and should be specified according to RFC 1766; examples include en for English, en-US for American English, and ja for Japanese. Whitespace is not allowed in the language code.

Use of the LANG attribute also allows authors to easily change the style of text depending on the language. For example, a bilingual document may have one language in italics if rendered visually or a different voice if rendered aurally. The HTML of such a document might be as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"
   "http://www.w3.org/TR/REC-html40/strict.dtd">
<TITLE>Welcome - Bienvenue</TITLE>
<H1>
  <SPAN LANG=en>Welcome</SPAN> -
  <SPAN LANG=fr>Bienvenue</SPAN>
</H1>
<P LANG=en>This paragraph is in English.</P>
<P LANG=fr>Ce paragraphe est en français.</P>
...

A document's primary language may be set using the LANG attribute on the HTML element, or, alternatively, by using the Content-Language HTTP header.

A number of attributes that define client-side scripting events are common to most elements. The attribute value is a script--typically a function call or a few short statements--that is executed when the event occurs. The value may contain entities (e.g., &quot;).

The following example features JavaScript code to handle two events of a submit button, giving the user a reminder in the status bar when the mouse moves over the button and clearing the status bar when the mouse moves away. Note that the attribute values are delimited by single quotes since double quotes are used within them.

<INPUT TYPE=submit ONMOUSEOVER='window.status="Did you fill in all required fields?";' ONMOUSEOUT='window.status="";'>

When an event attribute is used, a default scripting language must be specified for the document by setting the Content-Script-Type HTTP header to the media type of the scripting language. The previous example could use the following META element in the document's HEAD:

<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">

The common event attributes are device-dependent and largely tailored for the graphical user interface. The available events are as follows:

• ONCLICK, when the mouse button is clicked on an element;
• ONDBLCLICK, when the mouse button is double-clicked on an element;
• ONMOUSEDOWN, when the mouse button is pressed over an element;
• ONMOUSEUP, when the mouse button is released over an element;
• ONMOUSEOVER, when the mouse is moved onto an element;
• ONMOUSEMOVE, when the mouse is moved while over an element;
• ONMOUSEOUT, when the mouse is moved away from an element;
• ONKEYPRESS, when a key is pressed and released over an element;
• ONKEYDOWN, when a key is pressed down over an element;
• ONKEYUP, when a key is released over an element.