# @iress-oss/ids-components

> React component library for the Iress Design System — accessible, themeable UI primitives with built-in styling props, design tokens, and responsive layout support. All components use the `Iress` prefix (e.g. `IressButton`, `IressInput`).

- Install: `npm install @iress-oss/ids-components`
- Peer dependencies: `react`, `react-dom`, optionally `react-hook-form`
- Import CSS: `import '@iress-oss/ids-components/dist/style.css'`
- Wrap app in `<IressProvider>` for theming and context
- Storybook: <https://main--691abcc79dfa560a36d0a74f.chromatic.com>
- Structured AI index: `.ai/index.json` (machine-readable catalogue of all docs below)

## Components

- [Alert](.ai/components/alert.md): An alert displays a short, important message in a way that attracts the user's attention without interrupting the user's task.
- [Autocomplete](.ai/components/autocomplete.md): Autocomplete allow for users to fill in their input by providing suggestions as they type.
- [Recipes](.ai/components/autocomplete-recipes.md): Autocomplete component documentation.
- [Avatar](.ai/components/avatar.md): Avatars display user identity in a circular frame, with optional badge and type indicators.
- [Button](.ai/components/button.md): A button is a clickable item used to perform an action.
- [ButtonGroup](.ai/components/button-group.md): 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”.
- [Card](.ai/components/card.md): Cards are used to group small, related pieces of information into one digestible unit.
- [Checkbox](.ai/components/checkbox.md): 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
- [Checkbox Group](.ai/components/checkbox-group.md): Checkbox groups allow users to make more than one choice in a set of related options.
- [Recipes](.ai/components/checkbox-group-recipes.md): CheckboxGroup component documentation.
- [Col](.ai/components/col.md): Used in conjunction with the IressRow component to layout page content
- [Container](.ai/components/container.md): IressContainer provides a means to center and horizontally pad your site’s contents.
- [Divider](.ai/components/divider.md): A divider is a UI element that separates content in lists and layouts.
- [Expander](.ai/components/expander.md): Expanders are commonly used to reveal more information or details about an element or content on a page.
- [Field](.ai/components/field.md): The field component is used to place label, hint and error information around form controls.
- [Icon](.ai/components/icon.md): Icons enhance experiences by visually communicating meaning, actions, status, and feedback.
- [Image](.ai/components/image.md): IressImage renders an image that resizes based on the user's screen width. The component accepts standard image attributes like `src` and `alt`.
- [Inline](.ai/components/inline.md): IressInline renders a set of components in a row with equal spacing around them, wrapping onto multiple lines when necessary.
- [Input](.ai/components/input.md): Inputs allow a user to input and interact with data. This component should be used as a child of the IressField component to ensure the correct placement of elements like label, error & hint text.
- [Recipes](.ai/components/input-recipes.md): Input component documentation.
- [InputCurrency](.ai/components/input-currency.md): InputCurrency allows a user to input and interact with currency number. It works just like IressInput, with new props locale and currencyCode. This component meets ISO-4217 standard
- [Recipes](.ai/components/input-currency-recipes.md): InputCurrency component documentation.
- [Label](.ai/components/label.md): Use the IressLabel component when building bespoke form inputs and IressField is too restrictive.
- [Link](.ai/components/link.md): A link is used to navigate to another page or location.
- [Menu](.ai/components/menu.md): A menu can display grouped action buttons, navigation items or headings.
- [Menu Item](.ai/components/menu-item.md): Menu items are headings, buttons and dividers used inside an `IressMenu`
- [Modal](.ai/components/modal.md): Modals gather information, complete a subtask, or provide additional information without losing the context of an underlying page.
- [Panel](.ai/components/panel.md): A panel is used to group related content.
- [Pill](.ai/components/pill.md): Pills are used primarily for status updates, notifications and counts.
- [Placeholder](.ai/components/placeholder.md): A placeholder is a UI element that allows you to reserve space for content that has not been created yet, usually used for prototyping.
- [Popover](.ai/components/popover.md): A popover is panel that is toggled on/off by an activator button or text input. The panel is positioned relative to its activator element.
- [Recipes](.ai/components/popover-recipes.md): Popover component documentation.
- [Progress](.ai/components/progress.md): A progress component is used to indicate to a user the completion of a set of tasks or a process.
- [Provider](.ai/components/provider.md): Provider is a component that sets up the Iress Design System for your application. It ensures that the design system is correctly configured and ready to use.
- [Radio](.ai/components/radio.md): A radio is a single option presented with a radio button. It is used to select a single option from multiple options. It is typically used in an IressRadioGroup.
- [RadioGroup](.ai/components/radio-group.md): A radio group is a group of radio buttons that allows the user to select one option from multiple options, where all options are visible.
- [Readonly](.ai/components/readonly.md): Readonly displays a value that cannot be edited by the user. It renders a hidden input field to ensure the value is submitted with the form.
- [Row](.ai/components/row.md): Used in conjunction with the IressCol component to lay out page content.
- [Select](.ai/components/select.md): Selects provide select and multi-select functionality with the benefit of live filtering.
- [Skeleton](.ai/components/skeleton.md): Skeletons can increase perceived performance for users. As opposed to spinners, skeletons make it feel as though things are happening/loading immediately, then the information is incrementally displayed on the screen.
- [Recipes](.ai/components/skeleton-recipes.md): Skeleton component documentation.
- [SkipLink](.ai/components/skip-link.md): The skip link component allows keyboard users to quickly bypass the top-level navigation links and jump to the main content on a page.
- [Slideout](.ai/components/slideout.md): Slideouts are used to show additional information or to allow users to perform secondary tasks without leaving their normal workflow.
- [Slider](.ai/components/slider.md): Sliders provide a visual indication of adjustable content, where the user can select a value from a range usually represented on a horizontal track.
- [Spinner](.ai/components/spinner.md): Spinners notify the user that a task is being processed. They indicate that the app is busy, and should be used when the user has to wait for more than a few seconds.
- [Stack](.ai/components/stack.md): Use IressStack to control vertical spacing between content with consistent present values.
- [Styled](.ai/components/styled.md): The IressStyled component provides an unopinionated wrapper that gives you direct access to all supported styling properties. Use it when you need custom styling without creating a dedicated component or writing custom CSS.
- [Tab](.ai/components/tab.md): A tab is an interactive element that controls the display of other content, usually a panel
- [Tab Set](.ai/components/tab-set.md): Tabs are used to display modular pieces of related data that do not need to be compared or accessed simultaneously.
- [Table](.ai/components/table.md): Data driven component for displaying tabular data.
- [Tag](.ai/components/tag.md): Tags represent individual units in a group of selected items.
- [Text](.ai/components/text.md): The IressText component allows you to set typographic styles either on one element, or a block on HTML elements.
- [Toaster](.ai/components/toaster.md): Toaster provide users with important, time-sensitive information.
- [Toggle](.ai/components/toggle.md): Toggles allow users to turn things on or off. When toggled, the associated change happens straight away.
- [Tooltip](.ai/components/tooltip.md): A component that shows concise, informative text about an element when focussed upon, hovered over or on a long touch.
- [Validation message](.ai/components/validation-message.md): A validation message is used to inform the user of the status of a form input. If there are multiple messages, they can be combined using the IressValidationSummary component.

## Patterns

- [Breadcrumbs](.ai/patterns/breadcrumbs.md): Breadcrumbs are a secondary navigation aid that helps users understand their current location within the site hierarchy and provides a simple way to navigate back to higher-level pages.
- [Contextual Menu](.ai/patterns/contextual-menu.md): A compact overflow action pattern that surfaces contextual actions in a popover menu. Use this pattern for row-level or card-level secondary actions where space is constrained.
- [Dropdown Menu](.ai/patterns/dropdown-menu.md): A component designed to filter a section based on a list of options and quickly navigate to relevant content.
- [Feedback](.ai/patterns/feedback.md): Feedback components communicate information to users about actions, states, and processes. Choosing the right feedback component ensures users receive the right level of information at the right time without unnecessary disruption.
- [Form](.ai/patterns/form.md): Use the IressForm component when you want to request, validate and process data from the user.
- [Recipes](.ai/patterns/form-recipes.md): Form pattern documentation.
- [Loading](.ai/patterns/loading.md): The loading pattern is used to indicate that content is being loaded or processed consistently across Iress products. It can be used in various scenarios, such as loading entire applications, pages, components or server-side validation.
- [Shadow](.ai/patterns/shadow.md): The shadow pattern allows you to wrap your content in the shadow DOM, allowing you to isolate your styles from the rest of the application. This is useful when you want to create a component that has its own styles, without affecting the rest of the application (such as microfrontends).
- [SideNav](.ai/patterns/side-nav.md): A side navigation pattern that combines a rail (icon-only bar) with an expandable side menu panel. Provides a data-driven API where items are passed as an array, with the rail acting as the main navigation and the side menu showcasing children under each navigation group.

## Foundations & Guides

- [Core Design Principles](.ai/guides/foundations-principles.md): Principles guide documentation.
- [Accessibility](.ai/guides/foundations-accessibility.md): Accessibility is everyone's responsibility. It ensures that all users, regardless of their abilities or disabilities, can access and interact with our components effectively. This document outlines the key practices for building accessible components we follow within IDS.
- [Iconography](.ai/guides/foundations-iconography.md): Icons are a key part of the Iress Design System, providing visual cues and enhancing user experience. This section outlines the principles and guidelines for using icons effectively within our products.
- [Responsive layout](.ai/guides/foundations-responsive.md): The Iress Design System (IDS) is built with responsive design principles in mind. This means that our components are designed to adapt to different screen sizes and orientations, ensuring a consistent user experience across devices.
- [Z-index (stacking)](.ai/guides/foundations-zindex.md): The z-index determines the stacking order of elements. Elements with a higher z-index always sit in front of elements with a lower z-index. Each index has been mapped to the appropriate elevation(s).
- [Visual Design Standards](.ai/guides/foundations-visual-design.md): VisualDesign guide documentation.
- [Using components consistently](.ai/guides/foundations-consistency.md): Consistency guide documentation.
- [Content](.ai/guides/foundations-content.md): Content guide documentation.
- [User experience](.ai/guides/foundations-user-experience.md): We use heuristic guidelines to assess the usability and user-centred design quality of all Iress products.
- [Common mistakes](.ai/guides/foundations-common-mistakes.md): Patterns we see trip people up when building with IDS. Each section shows what goes wrong, why, and the fix.
- [Develop](.ai/guides/get-started-develop.md): Set up your environment to use the latest version of the Iress Design System (IDS). You can use this library to build React applications that align to IDS, and ensure a consistent and modern look and feel across all Iress products.
- [Content Security Policy (CSP)](.ai/guides/get-started-content-security-policy.md): IDS loads external stylesheets and fonts at runtime. If your application enforces a Content Security Policy, you need to allowlist the origins IDS loads from.
- [Migration from v4 to v5](.ai/guides/migration-guides-v5.md): This is a step-by-step guide for upgrading your application from IDS v4 to v5.
- [Migrating from v5 to v6](.ai/guides/migration-guides-v6.md): This guide covers all breaking changes, deprecations, and new features introduced in version 6 of the Iress Design System. While the list is extensive, most changes relate to look-and-feel rather than code.
- [Migrating from OUI to IDS v6](.ai/guides/migration-guides-oui.md): This guide covers migrating from the legacy OUI component library (`@iress/oui`) to the Iress Design System v6 (`@iress-oss/ids-components`). It also covers upgrading existing IDS v4 (`@iress/components-react`) components, replacing Formik with IDS v6's React Hook Form integration, and updating your test infrastructure.

## Styling Props

- [Styling props](.ai/guides/styling-props-reference.md): This page lists all the custom styling properties available in our components,
- [Accessibility](.ai/guides/styling-props-accessibility.md): These are all styling props related to screen readers and accessibility. They allow you to hide content from visual users while still providing context for screen reader users, ensuring an inclusive experience for all users.
- [Colour](.ai/guides/styling-props-colour.md): These are all styling props related to changing the foreground and background
- [Layout](.ai/guides/styling-props-layout.md): These are all styling props related to modifying layout.
- [Radius](.ai/guides/styling-props-radius.md): These are all styling props related to changing the radius of a component
- [Sizing](.ai/guides/styling-props-sizing.md): These are all styling props related to changing the size of a component,
- [Spacing](.ai/guides/styling-props-spacing.md): These are all styling props related to changing the spacing of a component.
- [Typography](.ai/guides/styling-props-typography.md): These are all styling props related to changing the typography of a component.

## Skills

- [Figma to IDS](.ai/skills/figma-to-ids.md): >
- [UI Doctor](.ai/skills/ui-doctor.md): >
- [UI Translation](.ai/skills/ui-translation.md): >
- [Version Migration](.ai/skills/version-migration.md): >

## Optional

- [Storybook (live)](<https://main--691abcc79dfa560a36d0a74f.chromatic.com>): Interactive component playground with all examples
- [GitHub Repository](<https://github.com/iress/design-system>): Source code and issue tracker
