<OptionRoot>, <OptionGroup>, and <Option>

Skip past table of contents

Search

Table of contents

Start of documentation content

The <Select>, <Radios> and <Checkboxes> share the same option components.

This makes it easy to change. If you used <Radios> but then decided to allow multiple selections it would be easy to swap to <Checkboxes>.

Intro

The multichoice <Select> and <Radios> and <Checkboxes> must only have a single child component of <OptionRoot>.

The <OptionRoot> may contain multiple <OptionGroup>s and <Option>s.

The <OptionGroup> may only contain multiple <Option>s, but no other component.

<OptionRoot>

The first and only child of <Select>, <Radios> or <Checkboxes> must be a single <OptionRoot>.

<OptionRoot> takes no props.

Valid children of <OptionRoot> are <OptionGroup>s and <Option>s.

Try changing <Select> to <Radios> or <Checkboxes>... the same <Option>s are shared by these 3 types of multichoice components.

<Select id="myMultichoice">

  <OptionRoot>

    <OptionGroup id="optionGroup1">

      <Option id="option1" />

    </OptionGroup>

    <Option id="option2" />

    <Option id="option3" />

  </OptionRoot>

</Select>

<OptionRoot>'s props

PropAboutType
meta

Arbitrary metadata on this node.

This is useful when developing custom controls as it allows you to pass down metadata/extensions.

string
childrenById

Used to indicate the ids of children.

If used in React this is non-editable.

string[]
hasChildrenById

Non-editable.

Used to indicate that this component has children.

true
id

Non-editable.

OptionRoot must be called "__root".

"__root"
isFormField

Non-editable.

Used to indicate that this component isn't a form field.

(form fields have labels and hints, this doesn't)

false
type

Non-editable.

Type of component of "OptionRoot".

"OptionRoot"

<OptionGroup>

<OptionGroup> groups sets of <Option>s. It cannot group any other component, including itself. This means that <OptionGroup> may only be top-level, and the grouping can only be one-level deep.

This component may only be used as a child of <OptionRoot>, and may not be nested.

The only valid children are <Option>s.

In a <Select> a <OptionGroup> would be rendered as an <optgroup> (MDN <optgroup>).

In <Checkboxes> and <Radios> this would be rendered as a <fieldset> (MDN <fieldset>).

Note: the hintHtml prop may be ignored when this multichoice is used in a <Select>. The reason for this is that the inbuilt (default) component uses a <Select> which doesn't have a place for hints. If you need hints in a <Select> then you'll need to override the default <Select> component, or use a <CustomField>.

Use of <OptionGroup>

<OptionGroup
  labelHtml={{ en: 'South Island', mi: 'Te Waipounamu }}
  hintHtml={{ en: '' }}
/>

<OptionGroup>'s props

PropAboutType
hintHtml

Localisable HTML: Hint content.

Note: If used in a <select> <optgroup> the hint may be ignored.

LocalisedHtml
labelHtml

Localisable HTML: Option Group title content.

Note that HTML might not be available if rendered as an <optgroup> in a <select>. In an <optgroup> The HTML will have tags striped, leaving plaintext.

If a developer requires HTML in a <select> then non-native controls would have to be used. See the controls prop and replace the <Select>.

HTML will be used in <Radios> and <Checkboxes>.

LocalisedHtml
id

Component Id.

Must be unique within the form.

string
meta

Arbitrary metadata on this node.

This is useful when developing custom controls as it allows you to pass down metadata/extensions.

string
childrenById

Used to indicate the ids of children.

If used in React this is non-editable.

string[]
hasChildrenById

Non-editable.

Used to indicate that this component has children.

true
isFormField

Non-editable.

Used to indicate that this component is a form field.

true
type

Non-editable.

Type of component of "OptionGroup".

"OptionGroup"

<Option>

An option that a user can choose.

In a <Select> this would be rendered as an <option>.

In <Checkboxes> these would be rendered as a checkbox field, and in <Radios> these would be a radio field.

Use of <Option>

<Option
  labelHtml={{ en: 'Green' }}
  hintHtml={{ en: 'E.g. #00ff00' }}
  value="green"
/>

Note: the hintHtml prop may be ignored when this multichoice is used in a <Select>. The reason for this is that the inbuilt (default) component uses a <Select> which doesn't have a place for hints. If you need hints in a <Select> then you'll need to override the default <Select> component, or use a <CustomField>.

<Option>'s props

PropAboutType
hintHtml

Localisable HTML: Hint content.

Note: If used in a <select>'s <option> it may be ignored

LocalisedHtml
labelHtml

Localisable HTML: Label content.

Note: If used in a <select>'s <option> then HTML tags may be stripped leaving plaintext.

LocalisedHtml
value

The 'value' attribute of the <option> or checkbox/radio <input>.

Typically not displayed to the user.

string
id

Component Id.

Must be unique within the form.

string
meta

Arbitrary metadata on this node.

This is useful when developing custom controls as it allows you to pass down metadata/extensions.

string
hasChildrenById

Non-editable.

Used to indicate that this element doesn't have children.

false
isFormField

Non-editable.

Used to indicate that this component is part of a form field.

true
type

Non-editable.

Type of component of "Option".

"Option"