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

#

| Chapter 21 JavaScript Reference |

# Checkbox Element

## Name

Checkbox Element---a graphical checkbox

## Availability

Navigator 2.0, Internet Explorer 3.0; enhanced in Navigator 3.0

## Synopsis

A single Checkbox element with a unique name may be referenced in any of these ways:

    form.checkbox_name
    form.elements[i]

When a form contains a group of checkboxes with the same name, they are placed in an array, and may be referenced as follows:

    form.checkbox_name[j]
    form.checkbox_name.length
    form.elements['name'][j]
    form.elements['name'].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 checkbox. May be specified with the HTML `CHECKED` attribute.

`form`

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

`name`

  A read-only String, set by the HTML `NAME` attribute, that specifies the name of the Checkbox.

`type`

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

`value`

  A read/write String, initially set by the HTML `VALUE` attribute, which specifies the value returned by the Checkbox if it is selected when the form is submitted.

## Methods

`blur()`

  Remove keyboard focus from the checkbox.

`click()`

  Simulate a click on the checkbox.

`focus()`

  Give keyboard focus to the checkbox.

## Event Handlers

`onblur()`

  Invoked when the checkbox loses keyboard focus.

`onclick()`

  Invoked when the checkbox is clicked.

`onfocus()`

  Invoked when the checkbox is given keyboard focus.

## HTML Syntax

A Checkbox element is created with a standard HTML `<INPUT>` tag, with the addition of the new `onClick` attribute. Multiple Checkbox elements are often created in groups by specifying multiple `<INPUT>` tags which have the same `NAME` attribute.

    <FORM>
        ...
      <INPUT
        TYPE="checkbox" specifies that this is a checkbox
        [ NAME="name" ]   a name that can later be used to refer to this checkbox
        or to the group of checkboxes with this name
        specifies the name property
        [ VALUE="value" ] the value returned when this checkbox is selected
        specifies the value property
        [ CHECKED ] specifies that the checkbox is initially checked
        specifies the defaultChecked property
        [ onClick="handler" ] JavaScript statements to be executed
      >  when the checkbox is clicked
    label the HTML text that should appear next to the checkbox
        ...
    </FORM>

## Description

The Checkbox element represents a single graphical checkbox in a HTML form. Note that the text that appears next to the checkbox is not part of the Checkbox element itself, and must be specified externally to the Checkbox's HTML `<INPUT>` tag.

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

You can examine the `checked` property to determine the state of the Checkbox, and you can also set this property to check or "uncheck" the Checkbox. Note that setting `checked` changes the graphical appearance of the Checkbox, but does not invoke the `onClick` event handler.

It is good programming style to specify the `NAME` attribute for a Checkbox, and is mandatory if the checkbox 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 Checkbox by name (instead of as a member of the form `elements` array) in your JavaScript code, which makes the code more modular and portable.

For example, if the `NAME` attribute of a checkbox in form `f` is "opts", then `f.opts` refers to the Checkbox element. Checkbox elements are often used in related groups, however, and each member of the group is given the same `NAME` attribute (the shared name defines the members of the group). In this case, JavaScript places each Checkbox element in the group in an array, and the array is given the shared name. If, for example, each of a group of Checkboxes in form `f` has its `NAME` attribute set to "opts", then `f.opts` is an array of Checkbox elements, and `f.opts.length` is the number of elements in the array.

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

You can set the `VALUE` attribute or the `value` property of a Checkbox to specify the string that will be passed to the server if the Checkbox is checked when the form is submitted. For a single checkbox, used alone, the default `value` of "on" is usually adequate. When multiple checkboxes with the same name are used, each should specify a distinct `value` so that a list of values from selected checkboxes can be passed to the server.

## Usage

Checkbox elements can be used to present the user with one or more options. This element type is suitable for presenting non-mutually exclusive choices. Use the Radio element for mutually exclusive lists of options.

## Bugs

As described above, when a group of Checkbox 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 Checkbox 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 your Checkbox elements that will be manipulated with JavaScript. You can do this by including `onClick="0"` in the `<INPUT>` tag for each Checkbox 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.

## See Also

"Element", "Form", "Radio"

Button.value |  | Checkbox.blur()