React

💡 Did you know

Cosmos' React wrapper is compatible with React 16.8+, 17, and 18.

React doesn't offer support for web components out of the box, thus integrating Cosmos web components requires some mediation between React and web components in order to gain full functionality.

To make working with Cosmos web components more convenient and practical, we providing a React wrapper library in the @cosmos/web-react package.

Use web components as first-class React components

The React wrapper hides all the quirks when working with web components and makes integrating Cosmos feel as native as working with React components. The Cosmos Rect wrapper takes care of the translation between React and web components by making the necessary adoptions, like translating properties to attributes and handling custom events to patch the missing support for web components.

Typescript support for properties, events, and methods

All Cosmos React web components are strongly typed to support using them correctly.

Auto-definition of required web components

The wrapping component takes care of registering and defining the required web components in the background the moment you are using the React component.

⚠️ Deprecation

With release v9.7.0 the React wrapper is provided as standalone package. For projects upgrading from a previous version, the dependencies and imports of the core package @cosmos/web have to be replaced with @cosmos/web-react. (deprecation roadmap)

"dependencies": {
  // "@cosmos/web": "9.6.0",
  "@cosmos/web-react": "9.7.0"
}

Usage

import React from "react";
import { render } from "react-dom";
import { CosmosButton } from "@cosmos/web-react";

const app = (
    <CosmosButton
      kind='tertiary'
      size='small'
    >
      Cosmos Button
    </CosmosButton>
);

render(app, window.document.body);

Custom Events

Subscribe to events emitted by Cosmos web components in JSX by prefixing capitalized event names with on .

import React from "react";
import { render } from "react-dom";
import { CosmosStoryCard } from "@cosmos/web-react";

const app = (
    <CosmosStoryCard
      observeMediaResize={true}
      onMediaresize={(event) => {
         console.log("media resized", event.detail);
      }}
    >
    </CosmosStoryCard>
);

render(app, window.document.body);

Typescript

All Cosmos React web components are strongly typed to ensure type-safe usage in Typescript environments.

import React from "react";
import { render } from "react-dom";
import { CosmosButton } from "@cosmos/web-react";
import type { CosmosButtonProps } from "@cosmos/web-react";


const buttonProps : CosmosButtonProps = {
  kind: 'tertiary',
  size: 'small',
  shape: 'rectangle',
  appearance: 'dark',
};

const App = () => (
    <CosmosButton
      {...buttonProps}
    >
      Cosmos Button
    </CosmosButton>
);

render(<App />, window.document.body);

Reference the Custom Element

Sometimes a reference to the underlying rendered custom element is required in order to call public methods or utilize the Javascript DOM API.

import React, { useEffect, useRef } from "react";
import { render } from "react-dom";
import { CosmosButton } from "@cosmos/web-react";
import type { CosmosButtonElement } from "@cosmos/web-react";

const App = () => {
  const buttonRef = useRef<CosmosButtonElement>(null);

  useEffect(() => {
    if(buttonRef.current) {
      console.log(buttonRef.current) // <cosmos-button>
    }
  })

  return (
    <CosmosButton ref={buttonRef}>
      Cosmos Button
    </CosmosButton>
  );
};

render(<App />, window.document.body);