@iress-oss/ids-components 6.0.0-alpha.5 → 6.0.0-alpha.51

package/.ai/components/alert.md

@@ -0,0 +1,183 @@
+# Alert
+
+An alert displays a short, important message in a way that attracts the user's attention without interrupting the user's task.
+
+> **Component:** `import { IressAlert } from '@iress-oss/ids-components'`
+> **Storybook:** [Alert in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-alert--docs)
+
+## Quick Start
+
+```tsx
+import { IressAlert } from '@iress-oss/ids-components';
+
+<IressAlert status="info">
+  This is a simple info alert
+</IressAlert>
+```
+
+## Usage
+
+### When to use
+
+- **Form validation**: Display errors or warnings near the relevant form section
+- **Page-level status**: Inform users about the state of the current page (e.g. "This record is read-only")
+- **Informational banners**: Provide tips, guidance, or announcements inline with content
+- **Persistent warnings**: Messages that should remain visible until the condition changes
+
+### When not to use
+
+- **Transient confirmations** of completed actions (e.g. "Saved") — use [IressToaster](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-toaster--docs) instead
+- **Tasks requiring user decisions** before continuing — use [IressModal](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-modal--docs) instead
+
+For a full comparison of feedback components, see the [Feedback pattern](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-feedback--docs).
+
+## Examples
+
+### Status
+
+The alert offers four statuses that set a distinctive colour and icon. They can be set using the `status` prop. Their different use cases are described here.
+
+```tsx
+<IressStack gap="md">
+{[...STATUSES, 'neutral'].map((status) => (
+<IressAlert status={status as never} key={status}>
+{messages[status as never]}
+</IressAlert>
+))}
+</IressStack>
+```
+
+[View "Status" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-alert--status)
+
+### Heading
+
+An alert can be displayed with a heading. This is controlled by the `heading` prop. If provided a string, it will display a `<h2 />` element with the string as its content. If provided a React element, it will display that element directly.
+
+**Note**: The `heading` prop replaces the `headingText` and `headingLevel` props from previous versions of IDS. These prop are now deprecated and will be removed in a future version.
+
+```tsx
+<IressAlert heading="Alert heading" />
+```
+
+[View "Heading" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-alert--heading)
+
+### Actions
+
+The `actions` prop allows you to display call to action buttons within the alert. This is useful for providing users with options to take action based on the alert message.
+
+```tsx
+<IressStack gap="md">
+<IressAlert status="danger" />
+<IressAlert status="info" />
+<IressAlert status="success" />
+<IressAlert status="warning" />
+<IressAlert status="neutral" />
+</IressStack>
+```
+
+[View "Footer" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-alert--footer)
+
+### Icon
+
+The `icon` prop allows you to customise the icon displayed in the alert. It accepts a string for the icon name, or can be set to `false` to remove the icon entirely.
+
+```tsx
+<IressAlert heading="Some information" multiLine icon={false}>
+  This is an alert without an icon
+</IressAlert>
+```
+
+[View "Icon" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-alert--icon)
+
+### Multi-line
+
+By default, the alert is designed to display short messages. If you need to display a longer message that spans multiple lines, you can set the `multiLine` prop to `true`. This will adjust the spacing and layout of the alert to accommodate longer content.
+
+```tsx
+<IressStack gap="md">
+<IressAlert status="danger" />
+<IressAlert status="info" />
+<IressAlert status="success" />
+<IressAlert status="warning" />
+<IressAlert status="neutral" />
+</IressStack>
+```
+
+[View "MultiLine" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-alert--multi-line)
+
+### Variants
+
+The alert can be displayed in different variants to suit different use cases. The `variant` prop allows you to set the variant of the alert. The available variants are:
+
+- `sidebar`: The alert is displayed in the sidebar of the page, typically used for informational messages on longer forms.
+- `full-width`: The alert is displayed in the site-wide banner, typically used for important messages that need to be seen by all users.
+
+```tsx
+<IressStack gap="md">
+<IressAlert variant="sidebar" />
+<IressAlert variant="full-width" />
+</IressStack>
+```
+
+[View "Variant" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-alert--variant)
+
+### Dimissable
+
+The alert can be made dismissable by setting the `onDismiss` prop. This will display a close button in the top right corner of the alert, allowing users to dismiss it.
+
+```tsx
+<IressStack gap="md">
+<IressAlert status="danger" />
+<IressAlert status="info" />
+<IressAlert status="success" />
+<IressAlert status="warning" />
+<IressAlert status="neutral" />
+</IressStack>
+```
+
+[View "Dismissable" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-alert--dismissable)
+
+## Testing
+
+Query the alert by its role. The role depends on the `status` prop:
+
+- `danger`, `warning`, `success` → `role="alert"` (assertive — interrupts screen readers)
+- `info` (default), `neutral` → `role="status"` (polite — announced at next pause)
+
+```tsx
+// danger/warning/success
+const alert = screen.getByRole('alert');
+
+// info/neutral
+const alert = screen.getByRole('status');
+```
+
+You can override the default role if needed:
+
+```tsx
+<IressAlert status="info" role="alert">Urgent info</IressAlert>
+```
+
+### Test IDs
+
+When you pass a `data-testid` to `IressAlert`, the following nested test IDs
+are generated automatically:
+
+| Suffix | Example | Description |
+| --- | --- | --- |
+| `heading` | `my-alert__heading` | The alert heading container |
+| `footer` | `my-alert__footer` | The alert footer/actions container |
+
+## Props
+
+- **Type:** `IressAlertProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Alert/Alert.d.ts`
+
+```typescript
+import type { IressAlertProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-alert--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-alert--docs)*

package/.ai/components/autocomplete-recipes.md

@@ -0,0 +1,29 @@
+# Recipes
+
+Autocomplete component documentation.
+
+> **Storybook:** [Recipes in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-autocomplete--docs)
+
+> [!NOTE]
+> **Experimental**
+>
+> This API is experimental. It may change in the future based on usage. The team
+>   is testing if these use cases exist and see if its worth maintaining this API.
+>   If you have any questions, concerns or feedback, please reach out to the
+>   design system team.
+
+## `useAutocompleteSearch`
+
+`IressAutocomplete` uses the `useAutocompleteSearch` hook to provide search functionality. If provided an array of `LabelValueMeta`, it will search options based on the `label` property. To fully customise how to search the objects, pass a function instead.
+
+It has been exposed in case you need it in your application to provide custom search functionality.
+
+### Use cases
+
+1. You want to provide filtering in a certain area of the application (eg. a table).
+
+[View "Table" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--table)
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-autocomplete--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-autocomplete--docs)*

package/.ai/components/autocomplete.md

@@ -0,0 +1,314 @@
+# Autocomplete
+
+Autocomplete allow for users to fill in their input by providing suggestions as they type.
+
+> **Component:** `import { IressAutocomplete } from '@iress-oss/ids-components'`
+> **Storybook:** [Autocomplete in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-autocomplete--docs)
+
+## Quick Start
+
+```tsx
+import { IressAutocomplete } from '@iress-oss/ids-components';
+
+<IressAutocomplete />
+```
+
+## Usage
+
+The `IressAutocomplete` element extends `IressInput` with additional functionality to provide suggestions to the user as they type.
+
+There is no validation done between the suggestions and the input value. They are strictly suggestions to improve the user experience. If you would like to restrict the input to the suggestions, you can use `IressCombobox`.
+
+### Uncontrolled
+
+The `defaultValue` prop can be used to set the initial value of the input. The value will be managed by the component.
+
+```tsx
+<IressAutocomplete defaultValue="Option 1" />
+```
+
+[View "Uncontrolled" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--uncontrolled)
+
+### Controlled
+
+The `value` prop can be used to completely control the state of the component. Use the `onChange` and `onClear` props to sync your state with the component.
+
+```tsx
+<AutocompleteUsingState />
+```
+
+[View "Controlled" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--controlled)
+
+### Providing suggestions
+
+#### `options`
+
+To use the suggestion functionality, you can provide an array of `LabelValueMeta[]` objects to the `options` prop.
+
+**Note:** If `value` is provided on a suggestion item, it will be used (casted to a string) instead of the `label` key. This is useful when you want to display a different value to the user than what is used for filtering.
+
+[View "Options" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--options)
+
+#### Asynchronous `options`
+
+If you would like to render suggestions from the server, you can pass a function to the `options` prop. It accepts a string parameter and returns a promise that resolves to an array of `LabelValueMeta[]` objects.
+
+```tsx
+<AutocompleteUsingAsync />
+```
+
+[View "AsyncOptions" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--async-options)
+
+#### Minimum search length for async options
+
+When using asynchronous options, you can set a minimum number of characters required before triggering the search using the `minSearchLength` prop. This prevents unnecessary API calls and loading states for very short queries.
+
+By default, async searches are triggered after 1 character. Setting a higher value (e.g., 3) means no search request will be made and no loading spinner will appear until the user types at least that many characters.
+
+```tsx
+<AutocompleteUsingAsync />
+```
+
+[View "AsyncOptionsMinSearchLength" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--async-options-min-search-length)
+
+#### `initialOptions`
+
+If you want to provide initial options to the user, you can use the `initialOptions` prop. This is useful when you want to provide a list of options to the user before they start typing (eg. recommended search terms).
+
+[View "InitialOptions" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--initial-options)
+
+## Behaviour
+
+- As long as there is a single character in the input, the suggestions will be displayed in a popover. Unless `initialOptions` are provided where the popover will be displayed immediately on focus.
+- The popover will close when the input is empty, unless `initialOptions` are provided.
+- The suggestions will be filtered based on the input value.
+- Tapping on a suggestion with the mouse will change the input value to the selection and close the popover.
+- When the user presses the arrows keys while the input is focussed, suggestions will be highlighted, but focus remains on the input.
+- When the user presses the enter key while a suggestion is highlighted, the suggestion will be selected and the popover will close.
+- When the user presses the down key while the popover is closed, it will open the popover.
+- When the user pressed the up key while the first suggestion is highlighted, it will close the popover.
+- When the user tabs away while no suggestion is highlighted, the input will not be changed.
+- When the user tabs away while a suggestion is highlighted, the suggestion will be selected.
+- When the user tabs away while the popover is open, the popover will close.
+
+## Accessibility
+
+The autocomplete component follows the [WAI combobox pattern: List autocomplete with manual selection](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#:~:text=List%20autocomplete%20with%20manual,value%20in%20the%20popup). An example of this pattern outside of IDS can be seen at [WAI-ARIA combobox example](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/).
+
+There is a key difference:
+
+- For better usability, virtual focus is used to highlight the suggestions inside the popover. This means focus remains on the input, but the suggestions are highlighted as if they are in focus, allowing the user to type and navigate the suggestions with the arrow keys.
+- To denote the highlighted suggestion to screen readers, the `aria-activedescendant` attribute is used.
+
+## Examples
+
+### `autoSelect`
+
+The `autoSelect` prop will automatically select the highlighted option when the user blurs the autocomplete. This is set to true by default, but can be switched off.
+
+```tsx
+<IressAutocomplete autoSelect={false} placeholder="Should no longer auto-select when an item is highlighted" />
+```
+
+[View "RemoveAutoSelect" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--remove-auto-select)
+
+### Input props
+
+Autocomplete extends `IressInput`, hence it has the same properties as `IressInput`.
+
+It does have some defaults to help with user experience. `append` automatically has a search icon, and `clearable` is set to true by default.
+
+```tsx
+<IressAutocomplete width={12} />
+```
+
+[View "InputProps" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--input-props)
+
+### No results
+
+If you would like to show a message when there are no results, you can use the `noResultsText` prop. It accepts any React node.
+
+```tsx
+<IressAutocomplete placeholder="Type "no" to see the no results text" />
+```
+
+[View "NoResultsText" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--no-results-text)
+
+### Popover props
+
+Under the hood, autocomplete uses `IressInputPopover` to display the suggestions. It accepts `autoHighlight`, `align`, `className` and `displayMode`.
+
+There are two additional props that autocomplete accepts to customise the popover: `append` and `prepend`. You can place additional content above or below the results using these props.
+
+[View "PopoverProps" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--popover-props)
+
+### Debounce threshold
+
+The `debounceThreshold` prop can be used to set the time in milliseconds to wait before making a request to the `options` function. This is useful when you want to prevent making too many requests to the server.
+
+By default there is a debounce, but it can be removed by setting it to `0`.
+
+```tsx
+<IressAutocomplete debounceThreshold={0} placeholder="Instant search!" />
+```
+
+[View "DebounceThreshold" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--debounce-threshold)
+
+### Result limits
+
+You can limit the maximum amount of search results displayed in the suggestions by setting the `limitDesktop` prop. This defaults to 12.
+
+On smaller screens (< 768px), the number of options is further reduced by using the `limitMobile` prop, which defaults to 6.
+
+`limitMobile` works by filtering the search results that have been filtered by `limitDesktop`, so must be a smaller value. For example:
+
+```tsx
+// 12 results on large screens, 6 on small screens (default values)
+<IressAutocomplete options={...} />
+
+// 4 results on large screens, 3 on small screens
+<IressAutocomplete resultLimitDesktop={4} resultLimitMobile={3} options={...} />
+
+// 4 results on all screens (resultLimitMobile > resultLimitDesktop so has no effect)
+<IressAutocomplete resultLimitDesktop={4} resultLimitMobile={5} options={...} />
+```
+
+The result limits will also affect the number of initial options displayed, if the `initialOptions` prop is set.
+
+```tsx
+<IressStack gap="md">
+<IressPanel>
+<CurrentBreakpoint />
+</IressPanel>
+<IressAutocomplete />
+</IressStack>
+```
+
+[View "ResultLimits" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--result-limits)
+
+### Read only
+
+The `readOnly` prop can be set to `true` to prevent the user from changing the value of the autocomplete. This will change the input to a custom read-only style and the user will not be able to interact with the input.
+
+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](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-readonly--docs).
+
+```tsx
+<IressAutocomplete readOnly />
+```
+
+[View "ReadOnly" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-autocomplete--read-only)
+
+## Testing
+
+To help you effectively test the autocomplete component, we have provided a few tips based on the behaviour of the component and our own experience.
+
+**Note:** These are suggestions and not requirements. You should test the component in a way that best suits your use case.
+
+### Partial query matching
+
+The suggestions are filtered based on the input value. If the input value only matches a part of the option, the input value is highlighted by a `<b />` tag in each option. You will need to account for this in your tests, either using an exact string match with a space to denote the highlighted value, or using a regex to match the string.
+
+If you are using `meta`, `prepend` or `append` props in `LabelValueMeta`, you should also consider this in your search query for the option.
+
+```tsx
+render(
+  <IressAutocomplete
+    options={[
+      { label: 'Luke Skywalker', value: 'Luke Skywalker', meta: 'male' },
+    ]}
+  />,
+);
+
+const autocomplete = screen.getByRole('combobox');
+await user.type(autocomplete, 'lu');
+
+// Exact string match with a space to denote the highlighted value
+const option = await screen.findByRole('option', {
+  name: 'Lu ke Skywalker male',
+});
+expect(option).toBeInTheDocument();
+
+// Using a regex to match the string
+const option = await screen.findByRole('option', { name: /Skywalker/ });
+expect(option).toBeInTheDocument();
+```
+
+### Query for minimal characters
+
+If you are testing if a specific option appears in the autocomplete that returns asynchronous `options`, it is recommended to use the shortest possible query to return the desired result. The longer the query, the longer it will take to see the results.
+
+```tsx
+render(<IressAutocomplete options={searchStarWarsCharacters} />);
+const autocomplete = screen.getByRole('combobox');
+
+// DO: Use the shortest query to return the desired result
+await user.type(autocomplete, 'lu');
+const option = await screen.findAllByRole('option');
+
+// DON'T: Use a long query to return the desired result
+await user.type(autocomplete, 'luke skywalker');
+const option = await screen.findAllByRole('option');
+```
+
+### Use mocking when testing APIs
+
+When testing the autocomplete component with asynchronous `options`, you should mock the API call to return a known set of results, rather than rely on a public prototyping API (eg. https://swapi.py4e.com/). This will allow you to test the component in isolation without relying on the API to return the expected results, as well as reduce chance of flakiness due to timeouts in your tests.
+
+We recommend using [Mock Service Worker](https://mswjs.io/) to mock the API calls in your tests.
+
+```tsx
+// src/mocks/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+  // Intercept "GET https://swapi.py4e.com/api/people" requests...
+  http.get('https://swapi.py4e.com/api/people', () => {
+    // ...and respond to them using this JSON response.
+    return HttpResponse.json([
+      { name: 'Luke Skywalker', gender: 'male' },
+      { name: 'Leia Skywalker', gender: 'female' },
+    ]);
+  }),
+];
+
+// src/mocks/node.js
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);
+
+// src/CustomAutocomplete.test.tsx
+import { server } from './mocks/node';
+
+server.listen();
+
+render(<IressAutocomplete options={searchStarWarsCharacters} />);
+const autocomplete = screen.getByRole('combobox');
+
+await user.type(autocomplete, 'lu');
+const option = await screen.findAllByRole('option');
+```
+
+### Test IDs
+
+When you pass a `data-testid` to `IressAutocomplete`, the following nested test
+IDs are generated automatically:
+
+| Suffix | Example | Description |
+| --- | --- | --- |
+| `input` | `my-autocomplete__input` | The underlying input element |
+| `menu` | `my-autocomplete__menu` | The suggestions menu |
+
+## Props
+
+- **Type:** `IressAutocompleteProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/Autocomplete/Autocomplete.d.ts`
+
+```typescript
+import type { IressAutocompleteProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-autocomplete--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-autocomplete--docs)*

package/.ai/components/button-group.md

@@ -0,0 +1,144 @@
+# ButtonGroup
+
+ButtonGroup allows users to switch between two or more possible states. ButtonGroups are only used for actions that occur immediately after the user “flips the switch”.
+
+> **Component:** `import { IressButtonGroup } from '@iress-oss/ids-components'`
+> **Storybook:** [ButtonGroup in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-button-group--docs)
+
+## Quick Start
+
+```tsx
+import { IressButtonGroup } from '@iress-oss/ids-components';
+
+<IressButtonGroup label="Options" />
+```
+
+## Usage
+
+Button Group requires some `label` text to describe what the group of buttons represent. The `label` text can be visually hidden (but still read by screenreaders) using the `hiddenLabel` prop.
+
+The `children` prop should contain multiple `IressButton` components.
+
+You can use the `onChange` prop to watch when a button is clicked.
+
+**Note:**
+
+- The `options` props, originally used to map a set of strings to `IressButton`, has been deprecated. Instead, you can use array.map to map the options to `IressButton` in your own application.
+- The `mode` prop on `IressButton` is not supported when used inside an `IressButtonGroup`.
+
+```tsx
+<IressButtonGroup label="Button group" />
+```
+
+[View "ButtonChildren" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button-group--button-children)
+
+## Examples
+
+### Rich buttons
+
+By passing the buttons as children you have more control over the display of the button allowing you to use icons or tooltips.
+
+**Note:** In this case, please set the `value` prop on the `IressButton` component to ensure the correct value is used when the button is clicked.
+
+```tsx
+<IressButtonGroup label="Text alignment" />
+```
+
+[View "RichButtons" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button-group--rich-buttons)
+
+### Multi-select
+
+By default, only one button in the group can be selected at a time. By setting the `multiple` prop, multiple buttons can be selected.
+
+```tsx
+<IressButtonGroup multiple label="Multiple options can be selected" />
+```
+
+[View "MultiSelect" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button-group--multi-select)
+
+### Pre-selecting buttons
+
+Buttons within the group can be pre-selected using the `defaultSelected` prop (for uncontrolled components), or the `selected` prop if you are planning to control the state yourself.
+
+If the button group is in its default single select mode, these props expects a string that matches the text of one of the buttons, or the `value` prop of the button if it has been set.
+
+In multi-select mode, these props expects an array of matching strings.
+
+```tsx
+<IressButtonGroup defaultSelected="Option 2" label="Selected option for single select" />
+```
+
+[View "SelectedSingle" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button-group--selected-single)
+```tsx
+<IressButtonGroup label="Selected option for multi-select" />
+```
+
+[View "SelectedMultiple" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button-group--selected-multiple)
+
+### `onChange` event
+
+The Button Group emits an event when any of the selected buttons change. The event detail (`ButtonGroupChange`) consist of a string or an array of strings (depending on if it's in single or multi select mode) that represents the selected button(s).
+
+```tsx
+const { success } = useToaster();
+
+    return (
+      <IressButtonGroup
+        {...args}
+        onChange={(selected) => {
+          success({
+            content: `Selected: ${selected ? String(selected) : 'none'}`,
+          });
+        }}
+      />
+    );
+```
+
+[View "OnChange" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button-group--on-change)
+
+### Hidden label
+
+If you would like to visually hide the label, you can use the `hiddenLabel` prop.
+
+```tsx
+<IressButtonGroup hiddenLabel />
+```
+
+[View "HiddenLabel" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button-group--hidden-label)
+
+### Headings as labels
+
+For semantic reasons, you may need the label to be rendered as a heading. In this case, you can pass the element directly to the `label` prop. The component will automatically add the `id` required to connect the button group to its label.
+
+[View "HeadingLabel" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-button-group--heading-label)
+
+## Testing
+
+Query the button group by its `group` role:
+
+```tsx
+const group = screen.getByRole('group', { name: 'Alignment' });
+```
+
+### Test IDs
+
+When you pass a `data-testid` to `IressButtonGroup`, the following nested test
+IDs are generated automatically:
+
+| Suffix | Example | Description |
+| --- | --- | --- |
+| `label` | `my-button-group__label` | The group label element |
+
+## Props
+
+- **Type:** `IressButtonGroupProps`
+- **Type declarations:** `@iress-oss/ids-components/dist/components/ButtonGroup/ButtonGroup.d.ts`
+
+```typescript
+import type { IressButtonGroupProps } from '@iress-oss/ids-components';
+```
+
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-button-group--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_components-button-group--docs)*