Using with Component Library

To ease migration effort, you might want to use Cimpress UI together with Component Library in a single project for a short amount of time. This guide outlines the steps necessary to setup such a hybrid solution.

Danger

This guide is meant for existing applications migrating away from Component Library. For new applications, please use Cimpress UI exclusively.

Requirements

You can use Cimpress UI and Component Library in a single project if:

• your project is currently using Component Library >= 16.21.0
• your project is not using the legacy MCP stylesheet (mcp-ux-css)

You might run into issues if:

• your project contains a styling solution that applies global styles (Bootstrap, Tailwind, etc.)

How it works

The hybrid solution can be thought of as Cimpress UI slowly “overtaking” Component Library by “colonizing” parts of the component tree.

Components from both libraries cannot be freely mixed. The developer needs to indicate which parts of the component tree are exclusively using Cimpress UI, and the rest of the component tree is assumed to exclusively use Component Library.

Marking an element with a Cimpress UI style root attribute will “claim” that element and all its descendants for exclusive Cimpress UI use. It will no longer be possible to use any Component Library components anywhere within that component tree. Similarly, components from Cimpress UI cannot be used outside of the marked component trees.

The GlobalStyles component from Component Library can still be rendered at the top of the component tree to provide global styles for Component Library components. The global styles will not affect any elements marked with data-cim-style-root or their descendants, ensuring that Cimpress UI components maintain their intended styling.

Setup

1. Make sure you have installed Cimpress UI by following the steps outlined in the installation guide for applications.

2. If you have added the data-cim-style-root attribute to your html element, remove it.

3. Add the data-cim-style-root attribute to the topmost element of every component tree which you want to “claim” for Cimpress UI.

Examples

Migrating a single component

Let’s assume that your application contains the following component built with Component Library:

src/example.tsx

import { Button, Checkbox } from '@cimpress/react-components';

export function Example() {
  const [isChecked, setIsChecked] = useState(false);
  const [isIndeterminate, setIsIndeterminate] = useState(false);

  return (
    <div style={{ display: 'flex' }}>
      <Checkbox
        label="Example"
        checked={isChecked}
        indeterminate={isIndeterminate}
        onChange={() => setIsChecked((prev) => !prev)}
      />
      <Button onClick={() => setIsIndeterminate((prev) => !prev)}>Toggle indeterminate state</Button>
    </>
  );
}

Now let’s assume that you want to replace the Button component from Component Library with its equivalent from Cimpress UI:

src/example.tsx

import { Button, Checkbox } from '@cimpress/react-components';
import { Checkbox } from '@cimpress/react-components';
import { Button } from '@cimpress-ui/react';

export function Example() {
  const [isChecked, setIsChecked] = useState(false);
  const [isIndeterminate, setIsIndeterminate] = useState(false);

  return (
    <div style={{ display: 'flex' }}>
      <Checkbox
        label="Example"
        checked={isChecked}
        indeterminate={isIndeterminate}
        onChange={() => setIsChecked((prev) => !prev)}
      />
      <Button onClick={() => setIsIndeterminate((prev) => !prev)}>Toggle indeterminate state</Button>
      <Button onPress={() => setIsIndeterminate((prev) => !prev)}>Toggle indeterminate state</Button>
    </>
  );
}

We’ve replaced the component itself, but now we also need to instruct both libraries that we’ve introduced Cimpress UI into this component tree.

src/example.tsx

import { Checkbox } from '@cimpress/react-components';
import { Button } from '@cimpress-ui/react';

export function Example() {
  const [isChecked, setIsChecked] = useState(false);
  const [isIndeterminate, setIsIndeterminate] = useState(false);

  return (
    <div style={{ display: 'flex' }}>
      <Checkbox
        label="Example"
        checked={isChecked}
        indeterminate={isIndeterminate}
        onChange={() => setIsChecked((prev) => !prev)}
      />
      <Button onPress={() => setIsIndeterminate((prev) => !prev)} data-cim-style-root>
        Toggle indeterminate state
      </Button>
    </>
  );
}

Now the Button component will be correctly displayed using Cimpress UI CSS rules, and Component Library will not apply its styles to it.

Migrating a component tree

Continuing the previous example, let’s assume that we now want to migrate the Checkbox component as well. Let’s do that using the steps we’ve outlined so far:

src/example.tsx

import { Checkbox } from '@cimpress/react-components';
import { Button } from '@cimpress-ui/react';
import { Button, Checkbox } from '@cimpress-ui/react';

export function Example() {
  const [isChecked, setIsChecked] = useState(false);
  const [isIndeterminate, setIsIndeterminate] = useState(false);

  return (
    <div style={{ display: 'flex' }}>
      <Checkbox
        label="Example"
        checked={isChecked}
        indeterminate={isIndeterminate}
        isChecked={isChecked}
        isIndeterminate={isIndeterminate}
        onChange={() => setIsChecked((prev) => !prev)}
        data-cim-style-root
      />
      <Button onPress={() => setIsIndeterminate((prev) => !prev)} data-cim-style-root>
        Toggle indeterminate state
      </Button>
    </>
  );
}

Everything works as expected, but there’s no more Component Library components left to migrate. We can now “claim” this entire component tree for Cimpress UI:

src/example.tsx

import { Button, Checkbox } from '@cimpress-ui/react';

export function Example() {
  const [isChecked, setIsChecked] = useState(false);
  const [isIndeterminate, setIsIndeterminate] = useState(false);

  return (
    <div style={{ display: 'flex' }}>
    <div style={{ display: 'flex' }} data-cim-style-root>
      <Checkbox
        label="Example"
        isChecked={isChecked}
        isIndeterminate={isIndeterminate}
        onChange={() => setIsChecked((prev) => !prev)}
        data-cim-style-root
      />
      <Button onPress={() => setIsIndeterminate((prev) => !prev)} data-cim-style-root>
      <Button onPress={() => setIsIndeterminate((prev) => !prev)}>
        Toggle indeterminate state
      </Button>
    </>
  );
}

All done! We can now repeat this process in other components within our application, until we reach the root html element.

Next steps

Once you’re ready to fully migrate away from Component Library, continue to Migrating from Component Library.