@iress-oss/ids-mcp-server 6.0.0-alpha.1-canary-20251204032753-fe18cab → 6.0.0-alpha.1-canary-20251204040305-3639454

package/generated/docs/components_components-checkbox-docs.md

@@ -0,0 +1,1083 @@
+Checkbox
+========
+
+Overview
+--------
+
+Checkboxes are used to let a user select one or more options for a limited number of choices. Also, works as a child of `IressCheckboxGroup`
+
+* * *
+
+Updated
+
+**Recently updated**
+
+This component has been recently updated with new props. The props have been marked as beta. Please tell us if there are any issues.
+
+[](./iframe.html?id=components-checkbox--default)
+
+A checkbox
+
+```
+
+<IressCheckbox\>
+  A checkbox
+</IressCheckbox\>
+
+```
+
+Props
+-----
+
+IressCheckboxIressCheckboxMark
+
+Tabs
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the checkbox is selected. Please use this when are rendering the checkbox in controlled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| children | 
+
+The checkbox content
+
+ReactNode
+
+
+
+ | \- | 
+
+"A checkbox"
+
+ |
+| defaultChecked | 
+
+If true, the checkbox will be initially rendered as selected. Please use this when are rendering the checkbox in uncontrolled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenControl | 
+
+Sets whether the control is hidden. If it is within a checkbox group, it will be overridden with the checkbox group's hiddenCheckbox setting.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenLabel | 
+
+Visually hides the label (if set), label will still be read out by screenreaders.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| indeterminate | 
+
+If true, the checkbox will visually appear as indeterminate.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| name | 
+
+The name of the control, which is submitted with the form data.
+
+string
+
+
+
+ | \- | Set string |
+| onBlur | 
+
+Emitted when the checkbox loses focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| onChange | 
+
+Emitted when the checkbox value changes.
+
+( e: ChangeEvent<HTMLInputElement>, checked?: boolean, value?: T, ) => void
+
+ | \- | \- |
+| onFocus | 
+
+Emitted when the checkbox gains focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| required | 
+
+If `true`, the checkbox is a required field and will be validated as such.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| touch | 
+
+Add the button-like border and padding to checkbox when `touch` is true.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of the checkbox when used in a checkbox group. The checked state of the checkbox will be overridden based on this value if used inside a checkbox group. **Note:**
+
+*   The value of the checkbox does not mean if its checked or not, use the checked property for that.
+*   If the value of the checkbox is true/false, and checked is undefined and not inside a CheckboxGroup, it will use this as the checked value. This ensures out-of-the-box compatibility with React Hook Form.
+
+T
+
+
+
+ | \- | Set object |
+
+Usage
+-----
+
+### Checked
+
+For single checkboxes in controlled mode the `checked` prop sets the checked state.
+
+When used as part of an `IressCheckboxGroup`, the `checked` prop will be ignored. Instead, the `value` prop on the `IressCheckboxGroup` will determine the checked state of each checkbox. See the [checkbox group documentation](?path=/docs/components-checkboxgroup--docs) for more details.
+
+[](./iframe.html?id=components-checkbox--checked)
+
+A checkbox which is checked and in controlled mode
+
+```
+
+<IressCheckbox checked\>
+  A checkbox which is checked and in controlled mode
+</IressCheckbox\>
+
+```
+
+#### Props
+
+IressCheckboxIressCheckboxMark
+
+Tabs
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the checkbox is selected. Please use this when are rendering the checkbox in controlled mode.
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| children | 
+
+The checkbox content
+
+ReactNode
+
+
+
+ | \- | 
+
+"A checkbox which is checked and in controlled mode"
+
+ |
+| defaultChecked | 
+
+If true, the checkbox will be initially rendered as selected. Please use this when are rendering the checkbox in uncontrolled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenControl | 
+
+Sets whether the control is hidden. If it is within a checkbox group, it will be overridden with the checkbox group's hiddenCheckbox setting.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenLabel | 
+
+Visually hides the label (if set), label will still be read out by screenreaders.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| indeterminate | 
+
+If true, the checkbox will visually appear as indeterminate.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| name | 
+
+The name of the control, which is submitted with the form data.
+
+string
+
+
+
+ | \- | Set string |
+| onBlur | 
+
+Emitted when the checkbox loses focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| onChange | 
+
+Emitted when the checkbox value changes.
+
+( e: ChangeEvent<HTMLInputElement>, checked?: boolean, value?: T, ) => void
+
+ | \- | \- |
+| onFocus | 
+
+Emitted when the checkbox gains focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| required | 
+
+If `true`, the checkbox is a required field and will be validated as such.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| touch | 
+
+Add the button-like border and padding to checkbox when `touch` is true.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of the checkbox when used in a checkbox group. The checked state of the checkbox will be overridden based on this value if used inside a checkbox group. **Note:**
+
+*   The value of the checkbox does not mean if its checked or not, use the checked property for that.
+*   If the value of the checkbox is true/false, and checked is undefined and not inside a CheckboxGroup, it will use this as the checked value. This ensures out-of-the-box compatibility with React Hook Form.
+
+T
+
+
+
+ | \- | Set object |
+
+### Default Checked
+
+For single checkboxes in uncontrolled mode the `defaultChecked` prop sets the default checked state.
+
+[](./iframe.html?id=components-checkbox--default-checked)
+
+A checkbox which is initially checked
+
+```
+
+<IressCheckbox defaultChecked\>
+  A checkbox which is initially checked
+</IressCheckbox\>
+
+```
+
+#### Props
+
+IressCheckboxIressCheckboxMark
+
+Tabs
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the checkbox is selected. Please use this when are rendering the checkbox in controlled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| children | 
+
+The checkbox content
+
+ReactNode
+
+
+
+ | \- | 
+
+"A checkbox which is initially checked"
+
+ |
+| defaultChecked | 
+
+If true, the checkbox will be initially rendered as selected. Please use this when are rendering the checkbox in uncontrolled mode.
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| hiddenControl | 
+
+Sets whether the control is hidden. If it is within a checkbox group, it will be overridden with the checkbox group's hiddenCheckbox setting.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenLabel | 
+
+Visually hides the label (if set), label will still be read out by screenreaders.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| indeterminate | 
+
+If true, the checkbox will visually appear as indeterminate.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| name | 
+
+The name of the control, which is submitted with the form data.
+
+string
+
+
+
+ | \- | Set string |
+| onBlur | 
+
+Emitted when the checkbox loses focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| onChange | 
+
+Emitted when the checkbox value changes.
+
+( e: ChangeEvent<HTMLInputElement>, checked?: boolean, value?: T, ) => void
+
+ | \- | \- |
+| onFocus | 
+
+Emitted when the checkbox gains focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| required | 
+
+If `true`, the checkbox is a required field and will be validated as such.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| touch | 
+
+Add the button-like border and padding to checkbox when `touch` is true.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of the checkbox when used in a checkbox group. The checked state of the checkbox will be overridden based on this value if used inside a checkbox group. **Note:**
+
+*   The value of the checkbox does not mean if its checked or not, use the checked property for that.
+*   If the value of the checkbox is true/false, and checked is undefined and not inside a CheckboxGroup, it will use this as the checked value. This ensures out-of-the-box compatibility with React Hook Form.
+
+T
+
+
+
+ | \- | Set object |
+
+### Indeterminate
+
+The `indeterminate` prop sets the checkbox appearance to an indeterminate dash until it is clicked. It has no impact on the checkbox behavior beyond this purely visual indicator.
+
+[](./iframe.html?id=components-checkbox--indeterminate)
+
+A checkbox which is initially in an indeterminate state
+
+```
+
+<IressCheckbox indeterminate\>
+  A checkbox which is initially in an indeterminate state
+</IressCheckbox\>
+
+```
+
+#### Props
+
+IressCheckboxIressCheckboxMark
+
+Tabs
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the checkbox is selected. Please use this when are rendering the checkbox in controlled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| children | 
+
+The checkbox content
+
+ReactNode
+
+
+
+ | \- | 
+
+"A checkbox which is initially in an indeterminate state"
+
+ |
+| defaultChecked | 
+
+If true, the checkbox will be initially rendered as selected. Please use this when are rendering the checkbox in uncontrolled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenControl | 
+
+Sets whether the control is hidden. If it is within a checkbox group, it will be overridden with the checkbox group's hiddenCheckbox setting.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenLabel | 
+
+Visually hides the label (if set), label will still be read out by screenreaders.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| indeterminate | 
+
+If true, the checkbox will visually appear as indeterminate.
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| name | 
+
+The name of the control, which is submitted with the form data.
+
+string
+
+
+
+ | \- | Set string |
+| onBlur | 
+
+Emitted when the checkbox loses focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| onChange | 
+
+Emitted when the checkbox value changes.
+
+( e: ChangeEvent<HTMLInputElement>, checked?: boolean, value?: T, ) => void
+
+ | \- | \- |
+| onFocus | 
+
+Emitted when the checkbox gains focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| required | 
+
+If `true`, the checkbox is a required field and will be validated as such.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| touch | 
+
+Add the button-like border and padding to checkbox when `touch` is true.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of the checkbox when used in a checkbox group. The checked state of the checkbox will be overridden based on this value if used inside a checkbox group. **Note:**
+
+*   The value of the checkbox does not mean if its checked or not, use the checked property for that.
+*   If the value of the checkbox is true/false, and checked is undefined and not inside a CheckboxGroup, it will use this as the checked value. This ensures out-of-the-box compatibility with React Hook Form.
+
+T
+
+
+
+ | \- | Set object |
+
+### Hidden Label
+
+It is very rare to want to render a checkbox without a visible label. However, one case where you might want to is within tables.
+
+When using a checkbox without a visible label, you must supply a label and apply the `hiddenLabel` property to still be accessible by screen readers.
+
+It is also important to not hide the table headers.
+
+[](./iframe.html?id=components-checkbox--with-table-data)
+
+List of investments
+| Select | Name | Date | Cost |
+| --- | --- | --- | --- |
+| 
+Toggle row
+
+ | Artemis Fund Managers Limited | 2019-09-23 | 23898.12 |
+| 
+
+Toggle row
+
+ | CASH.CASH | 2020-06-28 | 49751.43 |
+
+```
+
+<IressTable
+  caption\="List of investments"
+  columns\={\[
+    {
+      format: (value: boolean) \=> <IressCheckbox defaultChecked\={value} hiddenLabel\>Toggle row</IressCheckbox\>,
+      key: 'select',
+      label: 'Select',
+      sort: true
+    },
+    {
+      key: 'name',
+      label: 'Name'
+    },
+    {
+      key: 'date',
+      label: 'Date'
+    },
+    {
+      key: 'cost',
+      label: 'Cost'
+    }
+  \]}
+  rows\={\[
+    {
+      cost: 23898.12,
+      date: '2019-09-23',
+      name: 'Artemis Fund Managers Limited',
+      select: false
+    },
+    {
+      cost: 49751.43,
+      date: '2020-06-28',
+      name: 'CASH.CASH',
+      select: true
+    }
+  \]}
+/>
+
+```
+
+#### Props
+
+IressCheckboxIressCheckboxMark
+
+Tabs
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the checkbox is selected. Please use this when are rendering the checkbox in controlled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| children | 
+
+The checkbox content
+
+ReactNode
+
+
+
+ | \- | 
+
+"Toggle row"
+
+ |
+| defaultChecked | 
+
+If true, the checkbox will be initially rendered as selected. Please use this when are rendering the checkbox in uncontrolled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenControl | 
+
+Sets whether the control is hidden. If it is within a checkbox group, it will be overridden with the checkbox group's hiddenCheckbox setting.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenLabel | 
+
+Visually hides the label (if set), label will still be read out by screenreaders.
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| indeterminate | 
+
+If true, the checkbox will visually appear as indeterminate.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| name | 
+
+The name of the control, which is submitted with the form data.
+
+string
+
+
+
+ | \- | Set string |
+| onBlur | 
+
+Emitted when the checkbox loses focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| onChange | 
+
+Emitted when the checkbox value changes.
+
+( e: ChangeEvent<HTMLInputElement>, checked?: boolean, value?: T, ) => void
+
+ | \- | \- |
+| onFocus | 
+
+Emitted when the checkbox gains focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| required | 
+
+If `true`, the checkbox is a required field and will be validated as such.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| touch | 
+
+Add the button-like border and padding to checkbox when `touch` is true.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of the checkbox when used in a checkbox group. The checked state of the checkbox will be overridden based on this value if used inside a checkbox group. **Note:**
+
+*   The value of the checkbox does not mean if its checked or not, use the checked property for that.
+*   If the value of the checkbox is true/false, and checked is undefined and not inside a CheckboxGroup, it will use this as the checked value. This ensures out-of-the-box compatibility with React Hook Form.
+
+T
+
+
+
+ | \- | Set object |
+
+### Read only
+
+The `readOnly` prop changes how the checkbox is rendered. It will only render if the checkbox is checked (alongside a hidden input that contains the `value` if it was set), otherwise it will not be rendered.
+
+It is understandable that this may not be the desired behavior for all use cases. If you need a checkbox that is not editable, but still visible, simply do not set the `readOnly` prop and set the `checked` prop instead.
+
+[](./iframe.html?id=components-checkbox--read-only)
+
+I agree to the terms and conditions
+
+```
+
+<IressStack\>
+  <IressCheckbox
+    defaultChecked
+    readOnly
+    value\="readOnly"
+  \>
+    I agree to the terms and conditions  </IressCheckbox\>
+  <IressCheckbox
+    readOnly
+    value\="readOnly"
+  \>
+    I agree to the terms and conditions  </IressCheckbox\>
+</IressStack\>
+
+```
+
+#### Props
+
+IressCheckboxIressCheckboxMark
+
+Tabs
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the checkbox is selected. Please use this when are rendering the checkbox in controlled mode.
+
+boolean
+
+
+
+ | \- | \- |
+| children | 
+
+The checkbox content
+
+ReactNode
+
+
+
+ | \- | 
+
+"I agree to the terms and conditions"
+
+ |
+| defaultChecked | 
+
+If true, the checkbox will be initially rendered as selected. Please use this when are rendering the checkbox in uncontrolled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenControl | 
+
+Sets whether the control is hidden. If it is within a checkbox group, it will be overridden with the checkbox group's hiddenCheckbox setting.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenLabel | 
+
+Visually hides the label (if set), label will still be read out by screenreaders.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| indeterminate | 
+
+If true, the checkbox will visually appear as indeterminate.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| name | 
+
+The name of the control, which is submitted with the form data.
+
+string
+
+
+
+ | \- | Set string |
+| onBlur | 
+
+Emitted when the checkbox loses focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| onChange | 
+
+Emitted when the checkbox value changes.
+
+( e: ChangeEvent<HTMLInputElement>, checked?: boolean, value?: T, ) => void
+
+ | \- | \- |
+| onFocus | 
+
+Emitted when the checkbox gains focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| readOnly | 
+
+boolean
+
+
+
+ | \- | \- |
+| required | 
+
+If `true`, the checkbox is a required field and will be validated as such.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| touch | 
+
+Add the button-like border and padding to checkbox when `touch` is true.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of the checkbox when used in a checkbox group. The checked state of the checkbox will be overridden based on this value if used inside a checkbox group. **Note:**
+
+*   The value of the checkbox does not mean if its checked or not, use the checked property for that.
+*   If the value of the checkbox is true/false, and checked is undefined and not inside a CheckboxGroup, it will use this as the checked value. This ensures out-of-the-box compatibility with React Hook Form.
+
+T
+
+
+
+ | \- | 
+
+"readOnly"
+
+ |
+
+### Touch
+
+The `touch` prop adds the button-like border and padding to checkbox.
+
+[](./iframe.html?id=components-checkbox--touch)
+
+Checkbox with touch styles
+
+```
+
+<IressCheckbox touch\>
+  Checkbox with touch styles
+</IressCheckbox\>
+
+```
+
+#### Props
+
+IressCheckboxIressCheckboxMark
+
+Tabs
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the checkbox is selected. Please use this when are rendering the checkbox in controlled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| children | 
+
+The checkbox content
+
+ReactNode
+
+
+
+ | \- | 
+
+"Checkbox with touch styles"
+
+ |
+| defaultChecked | 
+
+If true, the checkbox will be initially rendered as selected. Please use this when are rendering the checkbox in uncontrolled mode.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenControl | 
+
+Sets whether the control is hidden. If it is within a checkbox group, it will be overridden with the checkbox group's hiddenCheckbox setting.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenLabel | 
+
+Visually hides the label (if set), label will still be read out by screenreaders.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| indeterminate | 
+
+If true, the checkbox will visually appear as indeterminate.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| name | 
+
+The name of the control, which is submitted with the form data.
+
+string
+
+
+
+ | \- | Set string |
+| onBlur | 
+
+Emitted when the checkbox loses focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| onChange | 
+
+Emitted when the checkbox value changes.
+
+( e: ChangeEvent<HTMLInputElement>, checked?: boolean, value?: T, ) => void
+
+ | \- | \- |
+| onFocus | 
+
+Emitted when the checkbox gains focus.
+
+(e: FocusEvent<HTMLInputElement>) => void
+
+ | \- | \- |
+| required | 
+
+If `true`, the checkbox is a required field and will be validated as such.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| touch | 
+
+Add the button-like border and padding to checkbox when `touch` is true.
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| value | 
+
+Value of the checkbox when used in a checkbox group. The checked state of the checkbox will be overridden based on this value if used inside a checkbox group. **Note:**
+
+*   The value of the checkbox does not mean if its checked or not, use the checked property for that.
+*   If the value of the checkbox is true/false, and checked is undefined and not inside a CheckboxGroup, it will use this as the checked value. This ensures out-of-the-box compatibility with React Hook Form.
+
+T
+
+
+
+ | \- | Set object |