webcomponents-react puts the SAP Fiori design system inside a React app

The React layer wraps web components, it does not reimplement them

The design of the package is the first thing to understand, because it explains both the benefits and the limitations. The repository description calls it a wrapper implementation for React of the UI5 Web Components that are compliant with the SAP Fiori User Experience, and the readme is blunter, saying it provides a Fiori-compliant React implementation by leveraging the UI5 Web Components. So the rendering, the behaviour and the styling of a control all live in the web component, and the React package is a typed facade over it. That has an obvious appeal for an enterprise team: the design system is the one SAP ships and supports, and the components behave the way the Fiori guidelines intend, rather than being a lookalike rebuilt in React. The cost is that the escape hatches of a native React component, a ref into the internals or a React-specific lifecycle, are not available in the usual form, because what sits behind the wrapper is a custom element.

Seven packages, and one of them is already deprecated

The packages overview is worth reading because the split tells you what each concern is separated into. The main package is @ui5/webcomponents-react. There is a charts package, @ui5/webcomponents-react-charts, which the listing marks as deprecated. There is a base package, @ui5/webcomponents-react-base, a legacy components package named @ui5/webcomponents-react-compat, and a wrapper generation and code modification package called @ui5/webcomponents-react-cli. Then there are two more: @ui5/webcomponents-cypress-commands, for custom Cypress commands and queries, and @ui5/webcomponents-ai-react, a React wrapper for the @ui5/webcomponents-ai package. The presence of a deprecation notice on the charts package and of a compat package for legacy components both point the same way, which is that this project has been through a generation change and the 2.x line is the current one.

Installation: two commands, or one if your bundler tree-shakes

The recommended install brings in the main package with its peer dependencies, the underlying components and the fiori package.

npm install @ui5/webcomponents-react @ui5/webcomponents @ui5/webcomponents-fiori

Since version 2.14.0 of the wrapper, the fiori package is an optional peer dependency, and the minimal install is therefore possible.

npm install @ui5/webcomponents-react @ui5/webcomponents

You still need the fiori package if you want to use any component from it, if you want the VariantManagement component, or if you import anything from it, and the readme adds that if you import from another @ui5 webcomponents package you should install that too even if it comes in through another package. The minimal installation is only genuinely smaller in the final bundle if your bundler tree-shakes, and most popular bundlers do, in which case there is no difference in bundle size between the two routes.

Without tree-shaking you need subpath imports or everything breaks

This is the sharpest constraint in the documentation and it deserves to be repeated because the failure is confusing. If your bundler does not support tree-shaking, you must use subpath imports, because the wrapper package re-exports all components, so every component, including those that depend on the fiori package, ends up in your bundle and produces errors from the missing module. The do and do not are shown directly.

import { Button } from '@ui5/webcomponents-react/Button';

import { Button } from '@ui5/webcomponents-react';

The first is correct and the second is not. The reasoning behind the rule is that the barrel file is what forces the whole component set to be pulled in, and a bundler that cannot drop the unused entries will fail at build time rather than at run time. A team picking this package should therefore establish which bundler it uses before it installs, since the answer decides whether the import style in the codebase is one form or the other.

Importing assets by hand is a Next.js workaround, not a preference

The assets section explains an unusual manual step. The default assets import pulls in assets from the fiori package, but because of a limitation in Next.js, where top-level await is not supported, the assets cannot be imported dynamically based on which packages are installed. So on a minimal installation you import them yourself, and the readme gives the four variants for browser, fetch and Node.

import '@ui5/webcomponents/dist/Assets.js';
import '@ui5/webcomponents-react/dist/json-imports/i18n.js';

The point for a reader is that the manual import is a consequence of a specific framework limitation rather than a stylistic choice by the project. A team that is not using Next.js has no such constraint and can use the default import, while a team that is using Next.js and the minimal install has to keep the manual imports in sync with whatever components they use. The i18n files come in the same set, which suggests the localisation bundles are part of the same asset loading story rather than a separate concern.

Version 1.x is over, and the documentation is published three ways

The end of support section is unambiguous: support for version 1.x ended on July 1, 2025, and the recommendation is to migrate to version 2.x as soon as possible, with a migration guide linked for the details. That timing matters for anyone still on the older line, because the wrapper generation and the component set both moved. The documentation itself is published in three flavours, a stable release, a nightly release and a version 1 release, each at its own path under the project pages, so a reader on 1.x can still find the old docs even though the code is no longer supported. The version list shows a steady sequence of patch releases, with 2.27.3, 2.27.2 and 2.27.1 published in the second half of September and October 2026, and the repository is a monorepo managed with yarn workspaces and lerna, with nx, storybook, cypress and playwright all wired into the scripts.

The test setup is three layers deep, which tells you what they worry about

The package scripts show a testing setup that is broader than most component libraries carry, and the reasons are visible in the tooling. The component tests run under cypress with the chrome browser, executed with yarn test:prepare and then cypress run against the packages, and there is a separate playwright suite with its own coverage path through nyc for a chromium project. A storybook build exists, with its own sitemap script and a search index built from the output directory. The custom Cypress commands package exists precisely so that component tests can query the web components in ways the stock commands do not support, since a custom element is not a DOM node React knows about. The overall effect is that this project treats the web component boundary as something to be tested rather than something to be assumed, which is the right instinct for a wrapper layer.

Where webcomponents-react is the wrong choice

The first wrong case is a project with a hard bundle budget and no tree-shaking in its bundler, because the barrel export then pulls in the whole component set, which is a structural property of the package rather than a bug you can configure around. The second is a team that wants to own its design system outright, since this package exists to deliver one specific design system and adopting it means adopting Fiori, along with its accessibility and interaction decisions. The third is a team already deeply invested in a different component library, because the value here is the Fiori look, and the components are not interchangeable with another set even though they are React elements. The fourth is a project that cannot accept the deprecation of the charts package or the separate legacy compat package, since that is a sign of how the release lines move. The fifth is an application that needs the web component's internals exposed, because a wrapper by definition presents a React-shaped interface and not the custom element underneath.

Editorial conclusion

Teams building enterprise applications that must look like SAP Fiori and want to write them in React, rather than embedding a design system that was designed for a different framework, are the people webcomponents-react is for, and the wrapper generation tooling is what keeps thousands of component wrappers in step with the underlying web components. It is the wrong choice for a team that wants a small dependency tree or a light bundle, because the wrapper package re-exports every component and the tree-shaking caveat in the documentation is not optional. Check three things before you adopt it: that your bundler supports tree-shaking, because without it every component including the ones that depend on the fiori package ends up in the bundle and produces errors from the missing module, which the readme states explicitly, that your React and React-DOM versions are 18.0.0 or higher, and that you are on version 2.x, since support for 1.x ended on July 1, 2025. The licence is Apache-2.0, the newest release is v2.27.3 from 2026-10-09, and the last push was on 2026-10-20.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. UI5/webcomponents-react on GitHub