@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-select-docs.md

@@ -0,0 +1,1110 @@
+Select
+======
+
+Overview
+--------
+
+Selects allow users to interact with data and select from a predetermined list of options.
+
+* * *
+
+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-select--options)
+
+Option 1Option 2Option 3Option 4Option 5
+
+```
+
+<IressSelect\>
+  <option value\="1"\>
+    Option 1  </option\>
+  <option value\="2"\>
+    Option 2  </option\>
+  <option value\="3"\>
+    Option 3  </option\>
+  <option value\="4"\>
+    Option 4  </option\>
+  <option value\="5"\>
+    Option 5  </option\>
+</IressSelect\>
+
+```
+
+Props
+-----
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+The `option` and `optgroup` elements to render within the select.
+
+union
+
+
+
+ | \- | \- |
+| defaultValue | 
+
+Value of selected option for uncontrolled select.
+
+T
+
+
+
+ | \- | Set object |
+| name | 
+
+Identifier for select.
+
+string
+
+
+
+ | \- | Set string |
+| onChange | 
+
+Handles the onChange event of the select input. If you pass in a non-string value, you can access it using the second parameter of the function.
+
+(e: ChangeEvent<HTMLSelectElement>, value?: T) => void
+
+ | \- | \- |
+| placeholder | 
+
+Adds an `option` as the first element with the placeholder text and no value.
+
+string
+
+
+
+ | \- | Set string |
+| readOnly | 
+
+If `true`, the user cannot modify the value.
+
+TReadonly
+
+
+
+ | \- | Set object |
+| required | 
+
+Mark the select as a required field.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of selected option for controlled select.
+
+T
+
+
+
+ | \- | Set object |
+| width | 
+
+The width of the select.
+
+intersection\['width'\]
+
+ | \- | Set object |
+
+Usage
+-----
+
+Selects allow users to interact with data and select from a predetermined list of options, usually when you are constrained for space and have a limited number of options to choose from.
+
+### When To Use
+
+*   If you have less than 5 options to choose from, consider using `IressRadioGroup` instead.
+*   If you need to display rich content in your selects (eg. icons and metadata), you can use `IressRichSelect`.
+*   Otherwise, `IressSelect` is the way to go.
+
+Examples
+--------
+
+### Options
+
+Individual options can be passed directly into `IressSelect` using the native `option` element.
+
+**Note:** The `mapSelectOptions` helper function, originally used to map options to `<option>` elements, is now deprecated. Instead, you can use `array.map` to map the options to `<option>` elements.
+
+[](./iframe.html?id=components-select--options)
+
+Option 1Option 2Option 3Option 4Option 5
+
+```
+
+<IressSelect\>
+  <option value\="1"\>
+    Option 1  </option\>
+  <option value\="2"\>
+    Option 2  </option\>
+  <option value\="3"\>
+    Option 3  </option\>
+  <option value\="4"\>
+    Option 4  </option\>
+  <option value\="5"\>
+    Option 5  </option\>
+</IressSelect\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+The `option` and `optgroup` elements to render within the select.
+
+union
+
+
+
+ | \- | \- |
+| defaultValue | 
+
+Value of selected option for uncontrolled select.
+
+T
+
+
+
+ | \- | Set object |
+| name | 
+
+Identifier for select.
+
+string
+
+
+
+ | \- | Set string |
+| onChange | 
+
+Handles the onChange event of the select input. If you pass in a non-string value, you can access it using the second parameter of the function.
+
+(e: ChangeEvent<HTMLSelectElement>, value?: T) => void
+
+ | \- | \- |
+| placeholder | 
+
+Adds an `option` as the first element with the placeholder text and no value.
+
+string
+
+
+
+ | \- | Set string |
+| readOnly | 
+
+If `true`, the user cannot modify the value.
+
+TReadonly
+
+
+
+ | \- | Set object |
+| required | 
+
+Mark the select as a required field.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of selected option for controlled select.
+
+T
+
+
+
+ | \- | Set object |
+| width | 
+
+The width of the select.
+
+intersection\['width'\]
+
+ | \- | Set object |
+
+### Option groups
+
+Just like the native `<select />` element, `IressSelect` supports option groups.
+
+[](./iframe.html?id=components-select--option-groups)
+
+Group 1 / Option 1Group 1 / Option 2Group 1 / Option 3Group 1 / Option 4Group 1 / Option 5Group 2 / Option 1Group 2 / Option 2Group 2 / Option 3Group 2 / Option 4Group 2 / Option 5
+
+```
+
+<IressSelect\>
+  <optgroup label\="Group 1"\>
+    <option value\="1-1"\>
+      Group 1 / Option 1    </option\>
+    <option value\="1-2"\>
+      Group 1 / Option 2    </option\>
+    <option value\="1-3"\>
+      Group 1 / Option 3    </option\>
+    <option value\="1-4"\>
+      Group 1 / Option 4    </option\>
+    <option value\="1-5"\>
+      Group 1 / Option 5    </option\>
+  </optgroup\>
+  <optgroup label\="Group 2"\>
+    <option value\="2-1"\>
+      Group 2 / Option 1    </option\>
+    <option value\="2-2"\>
+      Group 2 / Option 2    </option\>
+    <option value\="2-3"\>
+      Group 2 / Option 3    </option\>
+    <option value\="2-4"\>
+      Group 2 / Option 4    </option\>
+    <option value\="2-5"\>
+      Group 2 / Option 5    </option\>
+  </optgroup\>
+</IressSelect\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+The `option` and `optgroup` elements to render within the select.
+
+union
+
+
+
+ | \- | \- |
+| defaultValue | 
+
+Value of selected option for uncontrolled select.
+
+T
+
+
+
+ | \- | Set object |
+| name | 
+
+Identifier for select.
+
+string
+
+
+
+ | \- | Set string |
+| onChange | 
+
+Handles the onChange event of the select input. If you pass in a non-string value, you can access it using the second parameter of the function.
+
+(e: ChangeEvent<HTMLSelectElement>, value?: T) => void
+
+ | \- | \- |
+| placeholder | 
+
+Adds an `option` as the first element with the placeholder text and no value.
+
+string
+
+
+
+ | \- | Set string |
+| readOnly | 
+
+If `true`, the user cannot modify the value.
+
+TReadonly
+
+
+
+ | \- | Set object |
+| required | 
+
+Mark the select as a required field.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of selected option for controlled select.
+
+T
+
+
+
+ | \- | Set object |
+| width | 
+
+The width of the select.
+
+intersection\['width'\]
+
+ | \- | Set object |
+
+### Non-string values
+
+If you would like to introduce options with non-string values, you can use the `IressSelectOption` component to define your options.
+
+**Note:** Since the `onChange` event of a select relies on strings, it will try to find a string representation of the value. If you are using non-string values, you will need to ensure the `toString` conversion is unique per option.
+
+[](./iframe.html?id=components-select--non-string-values)
+
+Option 1Option 2Group 1 / Option 1Group 1 / Option 2Group 1 / Option 3
+
+```
+
+<IressSelect\>
+  <IressSelectOption value\={1}\>
+    Option 1  </IressSelectOption\>
+  <IressSelectOption value\={2}\>
+    Option 2  </IressSelectOption\>
+  <optgroup label\="Group 1"\>
+    <IressSelectOption value\="1-1"\>
+      Group 1 / Option 1    </IressSelectOption\>
+    <IressSelectOption value\="1-2"\>
+      Group 1 / Option 2    </IressSelectOption\>
+    <IressSelectOption value\="1-3"\>
+      Group 1 / Option 3    </IressSelectOption\>
+  </optgroup\>
+</IressSelect\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+The `option` and `optgroup` elements to render within the select.
+
+union
+
+
+
+ | \- | \- |
+| defaultValue | 
+
+Value of selected option for uncontrolled select.
+
+T
+
+
+
+ | \- | Set object |
+| name | 
+
+Identifier for select.
+
+string
+
+
+
+ | \- | Set string |
+| onChange | 
+
+Handles the onChange event of the select input. If you pass in a non-string value, you can access it using the second parameter of the function.
+
+(e: ChangeEvent<HTMLSelectElement>, value?: T) => void
+
+ | \- | \- |
+| placeholder | 
+
+Adds an `option` as the first element with the placeholder text and no value.
+
+string
+
+
+
+ | \- | Set string |
+| readOnly | 
+
+If `true`, the user cannot modify the value.
+
+TReadonly
+
+
+
+ | \- | Set object |
+| required | 
+
+Mark the select as a required field.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of selected option for controlled select.
+
+T
+
+
+
+ | \- | Set object |
+| width | 
+
+The width of the select.
+
+intersection\['width'\]
+
+ | \- | Set object |
+
+### Placeholder
+
+A default placeholder option can be set using the `placeholder` prop.
+
+[](./iframe.html?id=components-select--placeholder)
+
+Please select an optionOption 1Option 2Option 3Option 4Option 5
+
+```
+
+<IressSelect placeholder\="Please select an option"\>
+  <option value\="1"\>
+    Option 1  </option\>
+  <option value\="2"\>
+    Option 2  </option\>
+  <option value\="3"\>
+    Option 3  </option\>
+  <option value\="4"\>
+    Option 4  </option\>
+  <option value\="5"\>
+    Option 5  </option\>
+</IressSelect\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+The `option` and `optgroup` elements to render within the select.
+
+union
+
+
+
+ | \- | \- |
+| defaultValue | 
+
+Value of selected option for uncontrolled select.
+
+T
+
+
+
+ | \- | Set object |
+| name | 
+
+Identifier for select.
+
+string
+
+
+
+ | \- | Set string |
+| onChange | 
+
+Handles the onChange event of the select input. If you pass in a non-string value, you can access it using the second parameter of the function.
+
+(e: ChangeEvent<HTMLSelectElement>, value?: T) => void
+
+ | \- | \- |
+| placeholder | 
+
+Adds an `option` as the first element with the placeholder text and no value.
+
+string
+
+
+
+ | \- | Please select an option |
+| readOnly | 
+
+If `true`, the user cannot modify the value.
+
+TReadonly
+
+
+
+ | \- | Set object |
+| required | 
+
+Mark the select as a required field.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of selected option for controlled select.
+
+T
+
+
+
+ | \- | Set object |
+| width | 
+
+The width of the select.
+
+intersection\['width'\]
+
+ | \- | Set object |
+
+### Selected option
+
+An option can be selected by using either the `defaultValue` prop for uncontrolled components, or the `value` prop for controlled components.
+
+[](./iframe.html?id=components-select--selected-option)
+
+Option 1Option 2Option 3Option 4Option 5
+
+```
+
+<IressSelect defaultValue\={3}\>
+  <option value\="1"\>
+    Option 1  </option\>
+  <option value\="2"\>
+    Option 2  </option\>
+  <option value\="3"\>
+    Option 3  </option\>
+  <option value\="4"\>
+    Option 4  </option\>
+  <option value\="5"\>
+    Option 5  </option\>
+</IressSelect\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+The `option` and `optgroup` elements to render within the select.
+
+union
+
+
+
+ | \- | \- |
+| defaultValue | 
+
+Value of selected option for uncontrolled select.
+
+T
+
+
+
+ | \- | 
+
+3
+
+ |
+| name | 
+
+Identifier for select.
+
+string
+
+
+
+ | \- | Set string |
+| onChange | 
+
+Handles the onChange event of the select input. If you pass in a non-string value, you can access it using the second parameter of the function.
+
+(e: ChangeEvent<HTMLSelectElement>, value?: T) => void
+
+ | \- | \- |
+| placeholder | 
+
+Adds an `option` as the first element with the placeholder text and no value.
+
+string
+
+
+
+ | \- | Set string |
+| readOnly | 
+
+If `true`, the user cannot modify the value.
+
+TReadonly
+
+
+
+ | \- | Set object |
+| required | 
+
+Mark the select as a required field.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of selected option for controlled select.
+
+T
+
+
+
+ | \- | Set object |
+| width | 
+
+The width of the select.
+
+intersection\['width'\]
+
+ | \- | Set object |
+
+### Sizing
+
+Selects can be resized to suit a specific number of characters. This sets an expectation of what data is to be presented; for example using the `16` width for a credit card number.
+
+Widths can also be set as a percentage, allowing the input to take up a proportion of the width of its container.
+
+[](./iframe.html?id=components-select--sizing)
+
+2Option 1Option 2Option 3Option 4Option 5
+
+4Option 1Option 2Option 3Option 4Option 5
+
+6Option 1Option 2Option 3Option 4Option 5
+
+8Option 1Option 2Option 3Option 4Option 5
+
+10Option 1Option 2Option 3Option 4Option 5
+
+12Option 1Option 2Option 3Option 4Option 5
+
+16Option 1Option 2Option 3Option 4Option 5
+
+25percOption 1Option 2Option 3Option 4Option 5
+
+50percOption 1Option 2Option 3Option 4Option 5
+
+75percOption 1Option 2Option 3Option 4Option 5
+
+100percOption 1Option 2Option 3Option 4Option 5
+
+```
+
+<IressStack gap\="md"\>
+  <div\>
+    <IressSelect
+      placeholder\="2"
+      width\="2"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+  <div\>
+    <IressSelect
+      placeholder\="4"
+      width\="4"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+  <div\>
+    <IressSelect
+      placeholder\="6"
+      width\="6"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+  <div\>
+    <IressSelect
+      placeholder\="8"
+      width\="8"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+  <div\>
+    <IressSelect
+      placeholder\="10"
+      width\="10"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+  <div\>
+    <IressSelect
+      placeholder\="12"
+      width\="12"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+  <div\>
+    <IressSelect
+      placeholder\="16"
+      width\="16"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+  <div\>
+    <IressSelect
+      placeholder\="25perc"
+      width\="25perc"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+  <div\>
+    <IressSelect
+      placeholder\="50perc"
+      width\="50perc"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+  <div\>
+    <IressSelect
+      placeholder\="75perc"
+      width\="75perc"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+  <div\>
+    <IressSelect
+      placeholder\="100perc"
+      width\="100perc"
+    \>
+      <option value\="1"\>
+        Option 1      </option\>
+      <option value\="2"\>
+        Option 2      </option\>
+      <option value\="3"\>
+        Option 3      </option\>
+      <option value\="4"\>
+        Option 4      </option\>
+      <option value\="5"\>
+        Option 5      </option\>
+    </IressSelect\>
+  </div\>
+</IressStack\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+The `option` and `optgroup` elements to render within the select.
+
+union
+
+
+
+ | \- | \- |
+| defaultValue | 
+
+Value of selected option for uncontrolled select.
+
+T
+
+
+
+ | \- | Set object |
+| name | 
+
+Identifier for select.
+
+string
+
+
+
+ | \- | Set string |
+| onChange | 
+
+Handles the onChange event of the select input. If you pass in a non-string value, you can access it using the second parameter of the function.
+
+(e: ChangeEvent<HTMLSelectElement>, value?: T) => void
+
+ | \- | \- |
+| placeholder | 
+
+Adds an `option` as the first element with the placeholder text and no value.
+
+string
+
+
+
+ | \- | \- |
+| readOnly | 
+
+If `true`, the user cannot modify the value.
+
+TReadonly
+
+
+
+ | \- | Set object |
+| required | 
+
+Mark the select as a required field.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of selected option for controlled select.
+
+T
+
+
+
+ | \- | Set object |
+| width | 
+
+The width of the select.
+
+intersection\['width'\]
+
+ | \- | \- |
+
+### Read only
+
+Unlike the standard HTML `select` element, the `IressSelect` component can be set to `readOnly`. In this case, an `IressReadonly` component will render the selected label text, while the selected value is rendered in a hidden HTML `input` element for form submission.
+
+If you need more control over the read-only state (for example, rendering a stylised version of the value), you can use the [`IressReadonly` component](?path=/docs/components-readonly--docs).
+
+[](./iframe.html?id=components-select--read-only)
+
+Option 2
+
+```
+
+<IressSelect
+  readOnly
+  value\="2"
+\>
+  <option value\="1"\>
+    Option 1  </option\>
+  <option value\="2"\>
+    Option 2  </option\>
+  <option value\="3"\>
+    Option 3  </option\>
+  <option value\="4"\>
+    Option 4  </option\>
+  <option value\="5"\>
+    Option 5  </option\>
+</IressSelect\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+The `option` and `optgroup` elements to render within the select.
+
+union
+
+
+
+ | \- | \- |
+| defaultValue | 
+
+Value of selected option for uncontrolled select.
+
+T
+
+
+
+ | \- | Set object |
+| name | 
+
+Identifier for select.
+
+string
+
+
+
+ | \- | Set string |
+| onChange | 
+
+Handles the onChange event of the select input. If you pass in a non-string value, you can access it using the second parameter of the function.
+
+(e: ChangeEvent<HTMLSelectElement>, value?: T) => void
+
+ | \- | \- |
+| placeholder | 
+
+Adds an `option` as the first element with the placeholder text and no value.
+
+string
+
+
+
+ | \- | Set string |
+| readOnly | 
+
+If `true`, the user cannot modify the value.
+
+TReadonly
+
+
+
+ | \- | 
+
+true
+
+ |
+| required | 
+
+Mark the select as a required field.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| value | 
+
+Value of selected option for controlled select.
+
+T
+
+
+
+ | \- | 
+
+"2"
+
+ |
+| width | 
+
+The width of the select.
+
+intersection\['width'\]
+
+ | \- | Set object |