syncfusion-ej2-react-to-pure-react-migration-skill

# Syncfusion EJ2 React → Pure React Migration Global migration workflow and shared conventions for moving an app from Syncfusion EJ2 React to Syncfusion Pure React. > **Where to look for specifics:** > - **Component props / events / methods / enums / templates:** > `references/<componentName>.md` > - **EJ2-side API surface that the migration is moving away from:** the > Syncfusion EJ2 React documentation. > - **Per-component feature configuration** (filtering, paging, sorting, > virtualization, custom templates, sub-component composition, axis > options, etc.): `references/<componentName>.md`. > > SKILL.md is intentionally **not** a component API catalog. It only > documents rules that apply across multiple components or that govern how > migration work is performed. > **Availability:** Pure React components are available from > Syncfusion v29.2.4. Only a subset of EJ2 components has been published > in Pure React — if a target component is not listed in the > [component naming table](#component-naming) below, it has not been > published yet and cannot be migrated with Pure React alone. --- ## Source hierarchy When migrating a code surface, load information in this order: 1. `SKILL.md` — global migration workflow, package transformations, naming transformations, shared conventions, repository-wide patterns. 2. `references/<componentName>.md` — the component's own props / events / methods / enums / templates / interfaces / rendering behavior / feature configuration / component-specific limitations. `references/<componentName>.md` is the **primary source** for component migration — for any prop, method, union, enum, event, or other detail, consult that file, never SKILL.md. If guidance lives in both places, prefer the reference; only cross-cutting behavior belongs here. --- ## Component naming Drop the `Component` suffix on the EJ2 class to derive the Pure React identifier. A handful of components also change their root name: | EJ2 React | Pure React | EJ2 package area | | --- | --- | --- | | `AutoCompleteComponent` | `<Autocomplete>` | `ej2-react-dropdowns` | | `ButtonComponent` | `<Button>` | `ej2-react-buttons` | | `CalendarComponent` | `<Calendar>` | `ej2-react-calendars` | | `ChartComponent` | `<Chart>` | `ej2-react-charts` | | `CheckBoxComponent` | `<Checkbox>` | `ej2-react-buttons` | | `ChipListComponent` | `<Chip>` / `<ChipList>` (see reference file) | `ej2-react-buttons` | | `ComboBoxComponent` | `<ComboBox>` | `ej2-react-dropdowns` | | `ContextMenuComponent` | `<ContextMenu>` | `ej2-react-navigations` | | `DatePickerComponent` | `<DatePicker>` | `ej2-react-calendars` | | `DateRangePickerComponent` | `<DateRangePicker>` | `ej2-react-calendars` | | `DateTimePickerComponent` | `<DateTimePicker>` | `ej2-react-calendars` | | `DialogComponent` | `<Dialog>` | `ej2-react-popups` | | `DropDownButtonComponent` | `<DropDownButton>` | `ej2-react-splitbuttons` | | `DropDownListComponent` | `<DropDownList>` | `ej2-react-dropdowns` | | `FabComponent` | `<Fab>` | `ej2-react-buttons` | | `FormValidator` (class instance) | `<Form>` | `ej2-react-inputs` | | `GridComponent` | `<Grid>` | `ej2-react-grids` | | `ListViewComponent` | `<ListView>` | `ej2-react-lists` | | `MenuComponent` | `<Menu>` | `ej2-react-navigations` | | `MessageComponent` | `<Message>` | `ej2-react-notifications` | | `MultiSelectComponent` | `<MultiSelect>` | `ej2-react-dropdowns` | | `NumericTextBoxComponent` | `<NumericTextBox>` | `ej2-react-inputs` | | `RadioButtonComponent` | `<RadioButton>` | `ej2-react-buttons` | | `ScheduleComponent` | `<Scheduler>` | `ej2-react-schedule` | | `SkeletonComponent` | `<Skeleton>` | `ej2-react-notifications` | | `SplitButtonComponent` | `<SplitButton>` | `ej2-react-splitbuttons` | | `SwitchComponent` | `<Switch>` | `ej2-react-buttons` | | `TextAreaComponent` | `<TextArea>` | `ej2-react-inputs` | | `TextBoxComponent` | `<TextBox>` | `ej2-react-inputs` | | `TimePickerComponent` | `<TimePicker>` | `ej2-react-calendars` | | `ToastComponent` | `<Toast>` | `ej2-react-notifications` | | `ToolbarComponent` | `<Toolbar>` | `ej2-react-navigations` | | `TooltipComponent` | `<Tooltip>` | `ej2-react-popups` | | `AccumulationChartComponent` | `<PieChart>` | `ej2-react-charts` | > Components that already lack the suffix (e.g. `<Form>`, `<Menu>`) keep > their name. When in doubt, consult `references/<componentName>.md`. ### Collection directives → composite components EJ2 React uses framework-style `<XDirective>` / `<XCollectionDirective>` pairs. Pure React replaces these with dedicated sub-component compositions: - `<XDirective>` / `<XCollectionDirective>` patterns → read the per-component reference for the exact replacement component family. - `<Inject services={[Service]} />` — **drop entirely**. The feature is re-enabled in Pure React via the appropriate `*Settings` / `*Settings={{ enabled }}` prop on the root component — see the reference file for the component that owned the Inject. --- ## Package transformations EJ2 React packages share `@syncfusion/ej2-react-<area>`. Pure React packages drop the `ej2-` prefix; some areas also change their final segment: | EJ2 package | Pure React package | | --- | --- | | `@syncfusion/ej2-react-buttons` | `@syncfusion/react-buttons` | | `@syncfusion/ej2-react-calendars` | `@syncfusion/react-calendars` | | `@syncfusion/ej2-react-charts` | `@syncfusion/react-charts` | | `@syncfusion/ej2-react-dropdowns` | `@syncfusion/react-dropdowns` | | `@syncfusion/ej2-react-grids` | `@syncfusion/react-grid` | | `@syncfusion/ej2-react-inputs` | `@syncfusion/react-inputs` | | `@syncfusion/ej2-react-lists` | `@syncfusion/react-lists` | | `@syncfusion/ej2-react-navigations` | `@syncfusion/react-navigations` | | `@syncfusion/ej2-react-notifications` | `@syncfusion/react-notifications` | | `@syncfusion/ej2-react-popups` | `@syncfusion/react-popups` | | `@syncfusion/ej2-react-schedule` | `@syncfusion/react-scheduler` | | `@syncfusion/ej2-react-splitbuttons` | `@syncfusion/react-splitbuttons` | Areas not listed above have not yet been published as Pure React packages — do not attempt migration for those. --- ## License migration When migrating, update the license registration as shown below. ### Code-based registration **Before (EJ2 React):** ```tsx import { registerLicense } from '@syncfusion/ej2-base'; registerLicense('YOUR_LICENSE_KEY'); ``` **After (Pure React):** ```tsx import { registerLicense } from '@syncfusion/react-base'; registerLicense('YOUR_LICENSE_KEY'); ``` Register the license once during application startup (for example, in `main.tsx`) before rendering any Syncfusion components. ### CLI-based registration **Before (EJ2 React):** `npx syncfusion-license activate` **After (Pure React):** `npx syncfusion-react-license activate` The existing `syncfusion-license.txt` file and `SYNCFUSION_LICENSE` environment variable continue to work without changes. ### Summary | EJ2 React | Pure React | | --- | --- | | `@syncfusion/ej2-base` | `@syncfusion/react-base` | | `npx syncfusion-license activate` | `npx syncfusion-react-license activate` | | `syncfusion-license.txt` | No change | | `SYNCFUSION_LICENSE` | No change | --- ## Theming EJ2 React themes are CSS packages; Pure React theming replaces them with imports of themed CSS files. The Pure React side supports only `material`, `tailwind`, and `bootstrap`. Older EJ2 themes (Fabric, Fluent, Fluent 2, High Contrast, Tailwind 3, Bootstrap 4, Bootstrap 5, Bootstrap 5.3, Material 3) have no Pure React counterpart — the app must switch to one of the three supported themes. ### Theme import patterns Pick **one** of the two patterns in the migration target, using the appropriate theme package name as the value for `<themeName>`: ```css /* Component-scoped: ship styles for one component only. */ @import "@syncfusion/react-<themeName>-theme/styles/<componentName>/index.css"; /* Theme-global: ship styles for every component in the theme. */ @import "@syncfusion/react-<themeName>-theme/styles/<themeName>.css"; ``` `<themeName>` is one of `material`, `tailwind`, `bootstrap`. `<componentName>` is the Pure React component name — see the [component naming table](#component-naming). ### Theme migration workflow 1. Strip every `@syncfusion/ej2-*-theme` import from the codebase. 2. If the EJ2 theme is not `material`, `tailwind`, or `bootstrap`, switch to one of those three and remove the EJ2-only theme references. 3. Add the chosen Pure React theme import at the application root using either the component-scoped or theme-global pattern above. 4. Eyeball-test the app — Pure React CSS hooks are a visual redraw of the EJ2 themes and are not byte-identical. --- ## Version Pure React components are available from Syncfusion **v29.2.4**; the standalone Pure React theme packages require **v34.1.29** or later. See the [Version check](#version-check) subsection in the migration workflow for the major-version rule and the `node_modules` inspection rule. --- ## Icons EJ2 React icons come from `@syncfusion/ej2-icons` as CSS class strings (e.g. `e-icons e-add`). Pure React icons ship from `@syncfusion/react-icons` as React modules that you import and render as components. The specific icon names available, the way they accept color/size props, and any per-component `icon`/`iconCss` semantics are documented in each component's reference file. --- ## Shared migration conventions The conventions below are shared by multiple components. For the exact prop / event / method / enum / template names involved in a given component, read `references/<componentName>.md`. - **Drop `Component`/`Directive`/`CollectionDirective` suffixes** — see [Component naming](#component-naming). - **Strip `<Inject services={[...]} />`** — replaced by Settings props on the root component; details are per-component. - **Prefix event handlers with `on`** (e.g. `change` → `onChange`); any specific rename is in the per-component reference. - **Move locale and RTL off the component onto `<Provider>`** — see [Provider usage](#provider-usage). Same applies to `currencyCode`, `ripple`, and `animate` when they would otherwise repeat across components. - **Replace class refs with `useRef<T>(null)`** — see [Refs & imperative APIs](#refs--imperative-apis). - **Replace lifecycle props (`created`/`destroyed`) and imperative `destroy()` with React `useEffect`** — see [Lifecycle translation](#lifecycle-events--react-hooks). When a convention is mentioned in a reference file too, the reference file is authoritative for that component. ### Provider usage `<Provider>` is the Context-API wrapper for shared Syncfusion Pure React settings. It distributes direction, locale, currency code, ripple, and animation values to every Syncfusion Pure React component inside its subtree, so the application can configure shared behaviour once instead of repeating it on each component tag. The component is imported from `@syncfusion/react-base`. Migration for `enableRtl`, `Animation` from `@syncfusion/ej2-base` is hanlded like below in React with additional features. #### When it is required `<Provider>` is required whenever the migrated app needs any of the following to apply to more than one component at once: - The EJ2 `enableRtl` prop — must be lifted off individual components onto `<Provider dir="rtl">`. - The EJ2 `locale` prop — must be lifted off individual components onto `<Provider locale="…">`. - A default currency for components that render currency-formatted values — set `<Provider currencyCode="…">`. - A global ripple toggle — set `<Provider ripple={…}>`. - A global animation toggle — set `<Provider animate={…}>`. A single component that needs only one of these can still set the prop directly on its own tag. `<Provider>` is the mechanism for sharing a value across multiple components in the same scope. #### Context-sharing behavior `<Provider>` exposes its settings through React context. Every Syncfusion Pure React component inside the subtree automatically reads `dir`, `locale`, `currencyCode`, `ripple`, and `animate` from the nearest enclosing `<Provider>`. A component-level prop (when one exists) still overrides the Provider context for that single component; nested `<Provider>` scopes override the outer Provider. #### Migration patterns Prop renames when lifting from per-component to `<Provider>`: | EJ2 React prop | Pure React Provider prop | | --- | --- | | `enableRtl` | `dir="rtl"` | | `locale` | `locale` | | `currencyCode` | `currencyCode` | | `ripple` | `ripple` | | `animate` | `animate` | - Move `enableRtl` and `locale` off every component instance onto the enclosing `<Provider>` scope. - Use `<Provider>` for `currencyCode`, `ripple`, and `animate` when those values would otherwise repeat across components. - Nest `<Provider>` scopes when subtrees need different settings — the