Using Canvas

The primary way you will interact with Canvas will be with our Canvas Kit React library. Canvas Kit provides a set of components and primitives that can be used to implement user experiences consistent with the rest of Workday. As of v11, our library relies on the usage of our Tokens package for styling.

Canvas Kit

We support installation for existing projects and bootstrapping in a new project.

Installation

For an existing project, add the Canvas Kit React dependency with your preferred package manager.

With Yarn:

> yarn add @workday/canvas-kit-react

With npm:

> npm install --save @workday/canvas-kit-react

Canvas Tokens

This package provides Canvas design tokens for web applications. As of v11 our components rely on our Tokens Package. You must install and import the variables to ensure our components are styled correctly.

> yarn add @workday/canvas-tokens-web

Import the variables at the top level of your application to prevent duplicate imports and avoid unintentional overwrites. Import them in a native CSS file or in a JavaScript / TypeScript file as shown below.

/* index.css */
@import '@workday/canvas-tokens-web/css/base/_variables.css';
@import '@workday/canvas-tokens-web/css/system/_variables.css';
@import '@workday/canvas-tokens-web/css/brand/_variables.css';

// index.ts
import '@workday/canvas-tokens-web/css/base/_variables.css';
import '@workday/canvas-tokens-web/css/system/_variables.css';
import '@workday/canvas-tokens-web/css/brand/_variables.css';

For more information, view our Canvas Tokens docs.

Important: If your application lives within another application that already imports the CSS variables, you do not need to import these again. If you need tokens for local development, add them via a plugin or directly to the environment but do not ship code to production with duplicate token imports.

Canvas Kit Fonts

By default, no fonts are included with Canvas Kit modules. To use official Canvas Kit fonts, install and import the @workday/canvas-kit-react-fonts module.

Note that this module sources fonts from the Workday CDN.

Installation

yarn add @workday/canvas-kit-react-fonts

Usage

Canvas Kit components use the CSS-in-JS library emotion for styling. So the preferred method for adding fonts to a project is to use the library’s injectGlobal function from @emotion/css package. It will inject styles into the global scope. If you’re using Canvas Kit components already, you should have emotion added to your project. If not, start by adding it as a dependency.

yarn add @emotion/css

Then in your index or main file of your project…

import * as React from 'react';
import {createRoot} from 'react-dom/client';
import {injectGlobal} from '@emotion/css';
import {fonts} from '@workday/canvas-kit-react-fonts';
import {system} from '@workday/canvas-tokens-web';
import {cssVar} from '@workday/canvas-kit-styling';
 
import '@workday/canvas-tokens-web/css/base/_variables.css';
import '@workday/canvas-tokens-web/css/brand/_variables.css';
import '@workday/canvas-tokens-web/css/system/_variables.css';
 
import {App} from './App';
 
injectGlobal({
  ...fonts,
  'html, body': {
    fontFamily: cssVar(system.fontFamily.default),
    margin: 0,
    minHeight: '100vh',
  },
  '#root, #root < div': {
    minHeight: '100vh',
    ...system.type.body.small,
  },
});
 
const container = document.getElementById('root')!;
const root = createRoot(container);
root.render(<App />);

This ensures CSS tokens and fonts are loaded globally.

Bootstrapping

For a new project, we recommend using Workday’s Qbit CLI tool to bootstrap it. You can think of Qbit like Workday‘s very own Create React App, with support for standalone apps or apps/widgets built within the Workday context.

> npx @workday/qbit@latest create

Canvas Provider

The <CanvasProvider> is required for proper branding support. Furthermore, if you use Emotion for styling your components, the <CanvasProvider> ensures your styles will merge as expected. Note: Custom use of <CacheProvider> provided by Emotion is not supported. @workday/canvas-kit-styling owns the creating of the cache reference. This ensures both static styling and Emotion’s dynamic styling solutions work together. In most cases you’ll want to wrap your application at the root level in <CanvasProvider>.

import * as React from 'react';
import {
  CanvasProvider,
  ContentDirection,
  PartialEmotionCanvasTheme,
  useTheme,
} from '@workday/canvas-kit-react/common';
 
// Ensure CSS variables are defined. You Can also do this at the root index.css
import '@workday/canvas-tokens-web/css/base/_variables.css';
import '@workday/canvas-tokens-web/css/brand/_variables.css';
import '@workday/canvas-tokens-web/css/system/_variables.css';
 
export const App = () => {
  // useTheme is filling in the Canvas theme object if any keys are missing
  const canvasTheme: PartialEmotionCanvasTheme = useTheme({
    canvas: {
      // Switch to `ContentDirection.RTL` to change direction
      direction: ContentDirection.LTR,
    },
  });
 
  return (
    <CanvasProvider theme={canvasTheme}>
      <>
        <main>
          <p>Get Started With Canvas Kit</p>
        </main>
      </>
    </CanvasProvider>
  );
};

Usage

Now you’re ready to import our components.

import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {Flex} from '@workday/canvas-kit-react/layout';
import {
  plusIcon,
  relatedActionsVerticalIcon,
  caretDownIcon,
} from '@workday/canvas-system-icons-web';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  gap: system.space.x4,
  padding: system.space.x4,
});

const Example = () => (
  <Flex cs={parentContainerStyles}>
    <PrimaryButton>Primary</PrimaryButton>
    <PrimaryButton icon={plusIcon} iconPosition="start">
      Primary
    </PrimaryButton>
    <PrimaryButton icon={caretDownIcon} iconPosition="end">
      Primary
    </PrimaryButton>
    <PrimaryButton aria-label="Related Actions" icon={relatedActionsVerticalIcon} />
  </Flex>
);

For more information on how to use Canvas Kit components, check out their documentation in the Components section.

Resources

For more documentation, helpful links and other developer resources, check out the Resources page.

Reporting a Bug

If you spot a bug, inconsistency, or typo, please open a bug issue. Better yet, submit a pull request to addresses it.

Feature Requests

If you have an idea, we would love to hear about it. The best way to suggest a feature is to open a feature issue. The Canvas Kit core team will take a look and discuss it with you.

Questions

If you have a question, we are here to help! Reach out to the Canvas Kit core team on the #ask-canvas-kit channel on Slack.

Contributing

Want to contribute to Canvas Kit? Please read our contributing guidelines to find out more and how to get started.

Versioning

Canvas Kit follows semantic versioning and is enforced automatically by conventional commits (see “Commit Message Format”).