Breaking changes

​

Version 5.x breaking changes

​

Select component API changes

​

Value and onChange signature changes

value: T
onChange?: (value: T) => void

value: Option<T> | Option<T>[] | null
onChange?: (value: Option<T> | Option<T>[] | null) => void

• Update all value props to pass the full option object
• Update onChange handlers to receive and handle option objects
• Extract the value property when needed: option.value

​

Children render prop requirement

<FlxSelect
  options={options}
  value={value}
  onChange={setValue}
/>

<FlxSelect
  options={options}
  value={value}
  onChange={setValue}
>
  {(option, onClick, isSelected) => (
    <SelectOption option={option} onClick={onClick} isSelected={isSelected} />
  )}
</FlxSelect>

• Add a children render prop to all Select components
• Use the provided SelectOption component or create custom option rendering

​

Error prop type change

error?: FieldError

error?: boolean

• Convert FieldError objects to boolean: error={!!fieldState.error}
• Update type definitions if using TypeScript

​

New FlxSelectContainer component

<FlxSelect options={options} value={value} onChange={setValue} />

<FlxSelectContainer dataUniqueid="my-select" dataTestId="my-select">
  <FlxSelect options={options} value={value} onChange={setValue}>
    {(option, onClick, isSelected) => (
      <SelectOption option={option} onClick={onClick} isSelected={isSelected} />
    )}
  </FlxSelect>
</FlxSelectContainer>

• Wrap all Select components with FlxSelectContainer
• Move dataUniqueid and dataTestId props to the container

​

New listClassName prop

<FlxSelect
  optionClassName="option-style"
  listClassName="list-style"
  // ...
/>

• Review your styling to determine if you need separate list styling
• Move dropdown list styles to listClassName if needed

​

Option interface changes

interface Option<T> {
  value: T;
  label: string;
}

interface Option<T> {
  value: T;
  label: string;
  enabled?: boolean;
}

• Add enabled: false to options you want to disable
• Update option creation logic to include this property

​

Multi-select enhancements

​

New multi-select specific props

multiselect?: boolean
multiSelectSearch?: (props: MultiSelectSearchProps) => ReactElement | null
multiSelectSelections?: (props: MultiSelectSelectionsProps) => ReactElement | null
maxSelectable?: number
optionsDisplayMode?: MultiSelectOptionsDisplayModeType

• Set multiselect={true} for multi-select behavior
• Provide custom search and selection components if needed
• Set maxSelectable to limit selections
• Choose an optionsDisplayMode (defaults to COMMA_SEPARATED)

​

Multi-select value type

const [values, setValues] = useState<Option<string>[]>([]);

<FlxSelect
  value={values}
  onChange={(newValues) => setValues(newValues as Option<string>[])}
  multiselect={true}
/>

• Update state to handle arrays of options for multi-select
• Add type guards or type assertions as needed

​

Form control component removals

​

Removed components

• FlxFormField - Use Controller from react-hook-form instead
• FlxFormItem - Use native HTML structure instead
• FlxFormControl - Use native HTML structure instead
• FlxFormContent - Use native HTML structure instead

import { FlxFormField, FlxFormItem, FlxFormControl } from '@flowx/react-ui-toolkit';

<FlxFormField
  control={control}
  name="field"
  render={({ field }) => (
    <FlxFormItem>
      <FlxFormControl>
        <Input {...field} />
      </FlxFormControl>
    </FlxFormItem>
  )}
/>

import { Controller } from 'react-hook-form';

<Controller
  control={control}
  name="field"
  render={({ field }) => (
    <div className="form-field">
      <Input {...field} />
    </div>
  )}
/>

• Replace FlxFormField with Controller from react-hook-form
• Replace wrapper components with standard HTML elements
• Apply your own styling using CSS classes

​

Removed hooks

• useFormField - Use useFormContext or useController from react-hook-form instead

import { useFormField } from '@flowx/react-ui-toolkit';

const { error, invalid } = useFormField();

import { useFormContext } from 'react-hook-form';

const { formState } = useFormContext();
const error = formState.errors[fieldName];

• Replace with react-hook-form hooks directly
• Access form state through the form context

​

Icon system changes

​

Icon dictionary removal

import { Icon } from '@flowx/react-ui-toolkit';
import { IconDictionary } from '@flowx/react-ui-toolkit';

<Icon name={IconDictionary.CHECK} />
<Icon name={IconDictionary.CLOSE} />

import { Icon } from '@flowx/react-ui-toolkit';

<Icon name="check" />
<Icon name="close" />

• Replace all IconDictionary references with string literals
• Convert dictionary constant names to lowercase kebab-case
• Update TypeScript types if you have custom icon type definitions

​

Icon set structure change

lib/icon/Icon.dictionary.d.ts

lib/icon/icon_set/index.d.ts

• Update any direct imports of icon definitions
• Use the public Icon component API instead of internal icon sets

​

Dependency changes

​

Removed peer dependencies

• air-datepicker - Now a direct dependency
• ag-grid-react - Now a direct dependency

"peerDependencies": {
  "react": "~18",
  "react-dom": "~18",
  "air-datepicker": "~3",
  "ag-grid-react": "~32"
}

"peerDependencies": {
  "react": "~18",
  "react-dom": "~18"
}

• Remove air-datepicker and ag-grid-react from your package.json if only used by UI Toolkit
• Keep them if your application uses them directly

​

Removed internal dependencies

• react-hook-form - No longer a direct dependency (still supported as peer dependency)
• react-use-measure
• react-remove-scroll
• @react-spring/web
• @radix-ui/react-use-controllable-state
• @radix-ui/react-slot
• @radix-ui/react-use-previous

• Add react-hook-form to your dependencies if you use form controls
• Remove unused dependencies from your project

​

New dependencies

• @base-ui-components/react@1.0.0-beta.6 - New accessibility primitive library
• marked@12.0.2 - Bundled dependency
• marked-mangle@1.1.10 - Bundled dependency
• tabbable@6.2.0 - Bundled dependency

• No action required - these are bundled with the toolkit
• If you use @radix-ui primitives directly, continue including them in your dependencies

​

Component exports structure

​

New exports

export * from './lib/chip/Chip';

• Import and use the new Chip component for tags and selections

​

Multi-select specific exports

import { 
  MultiSelectOption,
  MultiSelectSearch,
  MultiSelectSelections 
} from '@flowx/react-ui-toolkit';

• Use these components for customizing multi-select behavior

​

TypeScript type changes

​

Generic type constraints

FlxSelectProps<unknown>

FlxSelectProps<T>

• Provide explicit type parameters: FlxSelectProps<string>
• Update component usage with proper generic types

​

Component prop types

• Update custom component wrappers with new prop types
• Use TypeScript’s IntelliSense to discover new props

​

Version 5.1.x changes

​

Version 5.2.x changes

​

Version 5.3.x changes

​

Version 5.4.x changes

​

Version 5.5.x changes

​

Version 4.7.x maintenance changes

​

Impact assessment summary

​

Critical (requires immediate attention)

• Select component value and onChange signature changes
• Select component children render prop requirement
• Form control component removals (FlxFormField, FlxFormItem, etc.)

​

High (requires code modifications)

• Error prop type change from FieldError to boolean
• FlxSelectContainer wrapper requirement
• useFormField hook removal

​

Medium (may require changes)

• Icon dictionary to string name conversion
• Multi-select API additions
• Dependency management updates
• TypeScript type refinements

​

Low (informational)

• New Chip component availability
• Internal dependency changes
• Component export structure changes

​

Migration timeline recommendation

​

Additional resources