webcomponents-react: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

Overview

UI5 Web Components for React is a React wrapper library for SAP's UI5 Web Components. It provides Fiori-compliant React components by wrapping native UI5 Web Components with React-specific implementations. The project is a monorepo managed with Lerna and Yarn workspaces.

Critical: Working with Web Components

Event Handling (MUST KNOW)

Web components emit CustomEvents with data in the detail property:

// ❌ WRONG - won't work with web components
const handleChange = (e) => {
  console.log(e.selectedOption); // undefined!
  console.log(e.value); // undefined!
};

// ✅ CORRECT - access via e.detail
const handleChange = (e) => {
  console.log(e.detail.selectedOption);
  console.log(e.detail.value);
};

For enriching events with additional data (internal use):

import { enrichEventWithDetails } from '@ui5/webcomponents-react-base/internal/utils';

onLoadMore(enrichEventWithDetails(e, { rowCount, totalRowCount }));

Controlled Components (MUST KNOW)

UI5 Web Components update internal state before firing events. For fully controlled components, call e.preventDefault() in the handler to prevent internal state updates (e.g., Input.onInput, CheckBox.onChange, Select.onChange, Dialog.onBeforeClose).

Ref Handling (MUST KNOW)

When a component needs both a forwarded ref and internal access to the same DOM node, use useSyncRef() instead of useRef():

import { useSyncRef } from '@ui5/webcomponents-react-base/internal/hooks';

const MyComponent = forwardRef((props, ref) => {
  const [componentRef, internalRef] = useSyncRef(ref);

  useEffect(() => {
    // internalRef gives stable access to the DOM node inside the component
    internalRef.current?.focus();
  }, []);

  // componentRef is passed to the DOM element so both the forwarded ref and internalRef stay in sync
  return <div ref={componentRef} />;
});