Skip to content
Cimpress UI

Installing (for applications)

Is this for me?

Section titled “Is this for me?”

You should use Cimpress UI in your application if:

  • you’re creating a new React application and you want it to have a Cimpress look and feel
  • you’re looking to migrate your existing React application from Component Library to a more modern solution

You may not use Cimpress UI in your application if:

  • your application doesn’t use React, or uses a React version older than 16.14

Project guidelines

Section titled “Project guidelines”

We recommend that your application 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 application 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”

Install the library using your project’s package manager:

Terminal window
npm install @cimpress-ui/react

Providing fonts

Section titled “Providing fonts”

Cimpress UI components require the Open Sans font. We recommend using Fontsource for installing the font in your application. Alternatively, you could load the font from Google Fonts.

  1. Install the font using your project’s package manager:

    Terminal window
    npm install @fontsource-variable/open-sans

  2. Import the font’s CSS files into the JS/TS entrypoint of your application:

    src/main.tsx
    import { StrictMode } from 'react';
    import { createRoot } from 'react-dom/client';
    import App from './app.js';
    

    import '@fontsource-variable/open-sans/wght.css';
    import '@fontsource-variable/open-sans/wght-italic.css';
    

    createRoot(document.getElementById('root')!).render(
      <StrictMode>
        <App />
      </StrictMode>,
    );

Including CSS

Section titled “Including CSS”

Cimpress UI provides its styles in a separate CSS file which your application needs to import. The library applies no global styles - instead, all styles are scoped to a data-cim-style-root attribute. You must apply this attribute to an element within your 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.

For most applications, you should import @cimpress-ui/react/styles.css which includes all necessary styles. For advanced use cases, the library also provides separate stylesheets:

  • @cimpress-ui/react/normalize.css - a normalization stylesheet (commonly called a “CSS reset”) that provides consistent styling across browsers
  • @cimpress-ui/react/core.css - the main stylesheet containing Cimpress UI’s design tokens and component styles

  1. Import the library styles into the JS/TS entrypoint of your application, right after the font imports:

    src/main.tsx
    import { StrictMode } from 'react';
    import { createRoot } from 'react-dom/client';
    import App from './app.js';
    

    import '@fontsource-variable/open-sans/wght.css';
    import '@fontsource-variable/open-sans/wght-italic.css';
    import '@cimpress-ui/react/styles.css';
    

    createRoot(document.getElementById('root')!).render(
      <StrictMode>
        <App />
      </StrictMode>,
    );

  2. Add a data-cim-style-root attribute to a chosen element within your DOM tree. For new applications, this will usually be the html element in your root HTML file:

    index.html
    <!doctype html>
    <html lang="en" data-cim-style-root>
      <head>
        <title>My App</title>
    

        ...
      </head>
      <body>
        ...
      </body>
    </html>

Next steps

Section titled “Next steps”

If you’re creating a new application with Cimpress UI, you can skip the rest of the “Getting Started” section.

If you’re migrating from Component Library and want to fully remove Component Library from your project, you can skip ahead to Migrating from Component Library.

If you’re migrating from Component Library and plan to use Cimpress UI together with Component Library, continue to Using with Component Library.