[Chapter 21] Reference: Radio
Author: David Flanagan
Date: Fri Aug 29 11:19:12 1997

#

| Chapter 21 JavaScript Reference |

# Radio Element

## Name

Radio Element---a graphical radio button

## Availability

Navigator 2.0, Internet Explorer 3.0; enhanced in Navigator 3.0

## Synopsis

The Radio button element is always 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
    form.elements[i][j]
    form.elements[i].length

## Properties

`checked`

  A read/write Boolean value that specifies whether the button is checked or not.

`defaultChecked`

  A read-only Boolean that specifies the initial state of the radio button. May be specified with the HTML `CHECKED` attribute.

`form`

  A read-only reference to the Form object that contains the Radio element.

`name`

  A read-only string, set by the HTML `NAME` attribute, that specifies the name of the Radio button.

`type`

  A read-only string that specifies the type of this form element. For Radio elements, it has the value "radio". Available in Navigator 3.0 and later.

`value`

  A read/write string, initially set by the HTML `VALUE` attribute, that specifies the value returned by the Radio button if it is selected when the form is submitted.

## Methods

`blur()`

  Removes keyboard focus from the radio button.

`click()`

  Simulates a click on the radio button.

`focus()`

  Gives keyboard focus to the radio button.

## Event Handlers

`onblur()`

  Invoked when the radio button loses keyboard focus.

`onclick()`

  Invoked when the radio button is clicked.

`onfocus()`

  Invoked when the radio button is given keyboard focus.

## HTML Syntax

A Radio element is created with a standard HTML `<INPUT>` tag, with the addition of the new `onClick` attribute. 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 that can later be used 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 represent mutually exclusive choices. When one button is selected, the previously selected button becomes deselected.

The `onClick` event handler allows you to specify JavaScript code to be executed when the button is checked or unchecked.

You can examine the `checked` property to determine the state of the button, and you can also 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 have the `CHECKED` attribute, then the first one in the group will be `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.

It is good programming style to specify the `NAME` attribute for a button, and is mandatory if the radio button is part of a form that will submit data to a CGI script running on a web server. Specifying a `NAME` attribute sets the `name` property, and also allows you to refer to the button by name (instead of as a member of the form `elements` array) in your JavaScript code, which makes the code more modular and portable.

Radio elements are used in groups of mutually exclusive options, and each member of the group is given the same `NAME` attribute (the shared name defines the members of the group). So if the shared name of a group of Radio elements in form `f` is "opts", then `f.opts` is an array of Radio elements, and `f.opts.length` is the number of elements in the array.

Unfortunately, in Navigator 2.0, there is a bug in how Radio elements in a group are assigned to an array. See the "Bugs" section for details.

You can set the `VALUE` attribute or the `value` property of a Radio element to specify the string that will be 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 that a script on the server can determine which one was checked when the form was submitted.

## Usage

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

## Bugs

As described above, when a group of Radio elements share the same `NAME` attribute, JavaScript assigns them to an array that bears that name. Unfortunately, there is a bug in this process in Navigator 2.0: if the radio elements do not have event handlers specified with the `onClick` attribute, then they are assigned to the array in reverse order. This is counter-intuitive, and is an incompatibility with Navigator 3.0 in which the bug is fixed.

The workaround is to always assign an event handler, if only a dummy one, to all of your Radio elements that will be manipulated with JavaScript. You can do this by including `onClick="0"` in the `<INPUT>` tag for each Radio element you define. With this workaround, you can ensure that the elements will be assigned to the array in the same order in Navigator 2.0 and Navigator 3.0.

At least some versions of Navigator do not correctly select the first radio button in a group when no buttons in the group have the `CHECKED` attribute specified. Therefore you should always explicitly specify the `CHECKED` attribute for one default selection in every radio button group.

## See Also

"Checkbox", "Element", "Form"

prompt() |  | Radio.blur()