Skip to content
Cimpress UI

Installing (for libraries)

Is this for me?

Section titled “Is this for me?”

You should use Cimpress UI in your library if:

  • you’re creating a new React library that exports UI components
  • you’re looking to migrate your existing React library from Component Library to a more modern solution

You may not use Cimpress UI in your library if:

  • your library doesn’t use React, or uses a React version older than 16.14
  • your library is already using Component Library and you want to keep using it for the time being

Project guidelines

Section titled “Project guidelines”

We recommend that your library follows our project guidelines in order to keep the Cimpress ecosystem healthy and modern.

Requirements

Section titled “Requirements”

In order to use Cimpress UI, your library must meet the following requirements:

  • React >= 16.14
  • if you use TypeScript:
    • TypeScript >= 4.7
    • moduleResolution set to node16, nodenext, or bundler

Installing the library

Section titled “Installing the library”

  1. Add Cimpress UI as a peer dependency to your library project. Specify a version range instead of a specific version - this will ensure that your library can be used with multiple versions of Cimpress UI.

    package.json
    ...,
    "peerDependencies": {
      "@cimpress-ui/react": "^1"
    },
    ...

  2. Add Cimpress UI as a development dependency. This will ensure that Cimpress UI is installed in your development environment.

    package.json
    ...,
    "peerDependencies": {
      "@cimpress-ui/react": "^1"
    },
    "devDependencies": {
      "@cimpress-ui/react": "^1.0.1"
    },
    ...

  3. Install the newly added dependencies using your library’s package manager:

    Terminal window
    npm install

  4. Instruct your consumers to install Cimpress UI in their applications. We recommend that you direct your consumers to our installation guide for applications.

Providing fonts

Section titled “Providing fonts”

Cimpress UI components require the Open Sans font. We recommend instructing your consumers to follow our font installation guide.

Including CSS

Section titled “Including CSS”

Cimpress UI provides its styles in a separate CSS file which the end-user applications need to import. The library applies no global styles - instead, all styles are scoped to a data-cim-style-root attribute. This attribute must be applied to an element within an end-user application’s DOM in order for the styles to take effect. The styles will only be applied to the element marked with the attribute, and to all its descendants.

We recommend instructing your consumers to follow our CSS guide.

If your library requires wrapping the end-user application with a React component or a React provider, you can include the scoping attribute within your markup:

src/MyProvider.tsx
import type { PropsWithChildren } from 'react';


export function MyProvider({ children }: PropsWithChildren<{}>) {
  /* Your existing provider logic */


  return (
    /* Your existing component tree */


        {children}
        <div data-cim-style-root>
          {children}
        </div>


    /* Your existing component tree */
  );
}

Next steps

Section titled “Next steps”

If you have a demo application for your library, follow your updated intructions for integrating your library into end-user applications. Note that this may now include steps from our installation guide for applications.

If you’re migrating your library away from Component Library, you can skip ahead to Migrating from Component Library.