Availability

JavaScript 1.0; enhanced in JavaScript 1.1

Inherits from/Overrides

Inherits from Input, HTMLElement

Synopsis

The Radio button element is usually used in groups of mutually exclusive options that have the same name. To reference one Radio element within a group, use this syntax:

form.radio_name[j]
form.radio_name.length 

Properties

Radio inherits properties from Input and HTMLElement and defines or overrides the following:

checked

A read/write boolean that is true if the radio button is checked or false otherwise. If you set checked to true, the radio button is selected, and the previously selected button is deselected. Note, however, that setting the checked property of a radio button to false has no effect, because at least one button must always be selected; you cannot deselect a radio button except by selecting some other button. Note also that setting the checked property does not cause the Radio button element's onclick event handler to be invoked. If you want to invoke that event handler, you must do so explicitly.

defaultChecked

A boolean property that is true if the radio button is initially selected, but only if the checked attribute appears in the button's HTML <input> tag. If this tag does not appear, the radio button is initially deselected, and defaultChecked is false.

value

A read/write string that specifies the text passed to the web server if the radio button is checked when the form is submitted. The initial value of this property is specified by the value attribute of the button's <input> tag. If the form is designed to be submitted to a server (as opposed to simply being used by JavaScript on the client side), each radio button in a group should have a distinct value. Note that the value field does not specify whether the radio button is currently selected; the checked property specifies the current state of the Radio object.

Methods

Radio inherits methods from Input and HTMLElement.

Event Handlers

Radio inherits event handlers from Input and HTMLElement and defines or overrides the following:

onclick

Invoked when the radio button is clicked.

HTML Syntax

A Radio element is created with a standard HTML <input> tag. Radio elements are created in groups by specifying multiple <input> tags that have the same name attribute:

<form>
    ...
  <input
    type="radio"           // Specifies that this is a radio button

    [ name="name" ]        // A name you can use later to refer to this button
                           // or to the group of buttons with this name
                           // Specifies the name property
    [ value="value" ]      // The value returned when this button is selected
                           // Specifies the value property
    [ checked ]            // Specifies that the button is initially checked
                           // Specifies the defaultChecked property
    [ onclick="handler" ]  // JavaScript statements to be executed when the button
                           // is clicked
  >
label                      // The HTML text that should appear next to the button
    ...
</form> 

Description

The Radio element represents a single graphical radio button in an HTML form. A radio button is one button in a group of buttons that represents mutually exclusive choices. When one button is selected, the previously selected button is deselected. The onclick event handler allows you to specify JavaScript code to be executed when the button is selected.

You can examine the checked property to determine the state of the button and set this property to select or deselect the button. Note that setting checked changes the graphical appearance of the button but does not invoke the onclick event handler. The initial value of the checked property and the value of the defaultChecked property are determined by the checked attribute. Only one Radio element in a group may contain this attribute -- it sets the checked and defaultChecked properties true for that element and false for all other radio buttons in the group. If none of the elements has the checked attribute, the first one in the group is checked (and defaultChecked) by default.

Note that the text that appears next to a radio button is not part of the Radio element itself and must be specified externally to the Radio's HTML <input> tag.

Radio elements are used in groups of mutually exclusive options. A mutually exclusive group is defined as the set of all Radio elements within a form that have the same name. If the shared name of a group of Radio elements in form f is opts, f.opts is an array of Radio elements, and f.opts.length is the number of elements in the array.

You can set the value attribute or the value property of a Radio element to specify the string that is passed to the server if the Radio element is checked when the form is submitted. Each Radio element in a group should specify a distinct value so a script on the server can determine which one was checked when the form was submitted.

Usage

Radio elements can present the user with a list of multiple mutually-exclusive options. Use the Checkbox element to present a single option or a list of options that are not mutually exclusive.

See Also

Checkbox, Form, Input; HTMLInputElement in DOM reference section