Canvas v12 Upgrade Guide

Upgrade Overview

The table below contains a high-level overview of the updates that will be rolled out as part of the v12 release. The impact for designers and developers are defined as follows:

• None: inapplicable to the role or no actions are required for users to adopt the change; updates will be applied automatically once users upgrade to Canvas Kit v12 and/or switch to the new v12 Canvas Web Figma library
• Low: minor changes are required for users to adopt the change
• Medium: a moderate amount of changes are required for users to adopt the change, such as switching out UI elements
• High: a large amount of changes are required for users to adopt the change, requiring product teams to make major design or development decisions

This guide contains an overview of the changes in Canvas Kit v12. Please reach out if you have any questions.

Why You Should Upgrade

Canvas Kit is transitioning into a new way of styling. Theming and building an in sync Canvas Kit CSS has been at the top of our minds. We’ve started using our new Canvas Tokens Web package to take advantage of CSS variables and provide semantic tokens that can translate to theming components.

A note to the reader:

• While we still support our old tokens from @workday/canvas-kit-react/tokens, you must install our new tokens from @workday/canvas-tokens-web. You can find more info in our docs.
• If your application lives within another application that already imports the CSS variables, you do not need to import these again.

Table of contents

• Canvas Tokens
• Codemod
  • Instructions
• Styling Updates
  • Compatibility Mode
• Deprecations
  • Form Field Container
• Removals
  • Input Icon Container
• Infrastructure
  • TypeScript
• Component Updates
  • Styling API and CSS Tokens
  • Avatar
  • Collections
  • Combobox
  • Form Field
    • Form Field Group
    • Form Field Field
  • Menu Item
  • MultiSelect
  • Search Form
  • Select
  • Text Area
  • Text Input
• Utility Updates
• Troubleshooting
• Glossary
  • Main
  • Preview
  • Labs

Canvas Tokens

In v12, all the components listed in this guide have started using our new Canvas Tokens Web. You must add @workday/canvas-tokens-web to ensure our components are properly styled and the variables are defined at the root of your application. For more information on installing and using, please reference our tokens docs.

Note: If your application lives within another application that already imports the CSS variables, you do not need to import these again. If you need them for local development either add them via a plugin or at the root of the environment, do not ship code to production duplicating the imports.

Codemod

We’ve provided a codemod to automatically update your code to work with most of the breaking changes in v12. Breaking changes handled by the codemod are marked with 🤖 in the Upgrade Guide.

Note: In v12, we have done some infrastructure updates with moving to Storybook 7, Webpack 5, TypeScript 5.0 and Cypress 13 . With these updates has come some formatting issues after running our codemods. We recommend running a formatter to address the format issues that have been introduced in v12.

A codemod is a script that makes programmatic transformations on your codebase by traversing the AST, identifying patterns, and making prescribed changes. This greatly decreases opportunities for error and reduces the number of manual updates, which allows you to focus on changes that need your attention. We highly recommend you use the codemod for these reasons.

If you’re new to running codemods or if it’s been a minute since you’ve used one, there are a few things you’ll want to keep in mind.

• Our codemods are meant to be run sequentially. For example, if you’re using v8 of Canvas Kit, you’ll need to run the v9 codemod before you run v10 and so on.
• The codemod will update your code to be compatible with the specified version, but it will not remove outdated dependencies or upgrade dependencies to the latest version. You’ll need to upgrade dependencies on your own.
  • We recommend upgrading dependencies before running the codemod.
  • Always review your package.json files to make sure your dependency versions look correct.
• The codemod will not handle every breaking change in v12. You will likely need to make some manual changes to be compatible. Use our Upgrade Guide as a checklist.
• Codemods are not bulletproof.
  • Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
  • As a safety precaution, we recommend committing the changes from the codemod as a single isolated commit (separate from other changes) so you can roll back more easily if necessary.

We’re here to help! Automatic changes to your codebase can feel scary. You can always reach out to our team. We’d be very happy to walk you through the process to set you up for success.

Instructions

The easiest way to run our codemod is to use npx in your terminal.

npx @workday/canvas-kit-codemod v12 [path]

Be sure to provide specific directories that need to be updated via the [path] argument. This decreases the amount of AST the codemod needs to traverse and reduces the chances of the script having an error. For example, if your source code lives in src/, use src/ as your [path]. Or, if you have a monorepo with three packages using Canvas Kit, provide those specific packages as your [path].

Alternatively, if you’re unable to run the codemod successfully using npx, you can install the codemod package as a dev dependency, run it with yarn, and then remove the package after you’re finished.

yarn add @workday/canvas-kit-codemod --dev
yarn canvas-kit-codemod v12 [path]
yarn remove @workday/canvas-kit-codemod

Note: The codemod only works on .js, .jsx, .ts, and .tsx files. You’ll need to manually edit other file types (.json, .mdx, .md, etc.). You may need to run your linter after executing the codemod, as its resulting formatting (spacing, quotes, etc.) may not match your project conventions.

Styling Updates

Compatibility Mode

In v12, we have addressed a style merge issue with removing forced compatibility mode. For more information on this change, please read our discussion.

Deprecations

We add the @deprecated JSDoc tag to code we plan to remove in a future major release. This signals consumers to migrate to a more stable alternative before the deprecated code is removed.

Form Field Container

PR: #2865

We’ve deprecated FormField.Container in v12. Please use FormField.Field or FormFieldGroup.Field for grouped inputs as this ensures proper label alignment and spacing of inputs and hint text, regardless of the orientation.

// v11
<FormField>
  <FormField.Label>Email</FormField.Label>
  <FormField.Container>
    <FormField.Input as={TextInput} />
    <FormField.Hint>You must provide an email</FormField.Hint>
  </FormField.Container>
</FormField>
 
// v12
<FormField>
  <FormField.Label>Email</FormField.Label>
  <FormField.Field>
    <FormField.Input as={TextInput} />
    <FormField.Hint>You must provide an email</FormField.Hint>
  </FormField.Field>
</FormField>

Removals

Removals are deletions from our codebase and you can no longer consume this component. We’ve either promoted or replaced a component or utility.

Input Icon Container

PR: #2838

We’ve removed InputIconContainer from Main. Please use InputGroup from Main instead.

Infrastructure

TypeScript

PR: #2908

We’ve upgraded to TypeScript 5.0 to make use of const Type Parameters. You will need to upgrade to TypeScript 5.0+ to avoid any TypeScript syntax errors. TypeScript does not follow semver, so 5.0 doesn’t mean a large breaking change from 4.9. TypeScript doesn’t have a x.10 release, they bump the x.9 to {x+1}.0.

Component Updates

Styling API and CSS Tokens

PRs: #2793, #2865, #2881, #2825, #2795,

Several components have been refactored to use our new Canvas Tokens and styling API. The React interface has not changed, but CSS variables are now used for dynamic properties.

Note: These components also support our new cs prop for styling. Learn more about styling with cs in our documentation.

The following components are affected:

• Avatar
• Dialog
• Modal
• Popup
• TextArea
• TextInput
• Toast

Avatar

PR #2793

Avatar has been updated to use our new styling utilities. The following changes have been made to the API:

• Avatar.Size has been deprecated. The size prop still accepts Avatar.Size in addition to the following values: "extraExtraLarge" | "extraLarge" | "large" | "medium" | "small" | "extraSmall" | (string{})
• Avatar.Variant has been deprecated. The variant prop still accepts Avatar.Variant in addition to the following values: "dark" | "light"
• The as prop now accepts any element, not just a div.

Note: Both Avatar.Size and Avatar.Variant have been deprecated in favor of the new string union types. You will see a console warn message while in development if you’re still using this. Please update your types and usage before v13.

Combobox

PR #2983

The useComboboxInput hook, and the Combobox.Input component used to automatically update the input when an option was selected. This functionality has been split between useComboboxInputArbitrary and useComboboxInputConstrained depending on the combobox’s value type. The useComboboxInput had the arbitrary functionality built in. This has been separated out. The <Select> component has been updated to use useComboboxInputConstrained hook and the Autocomplete example uses the useComboboxInputArbitrary hook. This is a breaking change if you use the Combobox.Input component directly. You’ll have to either pass the useComboboxInputArbitrary elemProps hook directly to the <Combbox.Input> or create a new component composing them.

// v11
<Combobox>
  <Combobox.Input />
  // ...
</Combobox>
 
// v12
<Combobox>
  <Combobox.Input elemPropsHook={useComboboxInputArbitrary} />
  // ...
</Combobox>
 
// Better - create a specialized component
const useMyComboboxInput = composeHooks(
  // or your own model that extends `useComboboxModel`
  createElemPropsHook(useComboboxModel)(model => {
    return {
      // anything you need your input to do
    }
  }),
  useComboboxInputArbitrary,
  useComboboxInput
)
 
const MyComboboxInput = createSubcomponent(TextInput)({
  // or your own model that extends `useComboboxModel`
  modelHook: useComboboxModel,
  elemPropsHook: useMyComboboxInput,
})((elemProps, Element) => {
  // return a TextInput
  return <Element {...elemProps} />
 
  // return an InputGroupgs
  return (
    <InputGroup>
      <InputGroup.InnerStart>{/* Icon or something */}</InputGroup.InnerStart>
      <InputGroup.Input as={Element} {...elemProps} />
      <InputGroup.InnerEnd><InputGroup.ClearButton /></InputGroup.InnerEnd>
    </InputGroup>
  )
})

Form Field

PRs: #2865, #2881, #2934, #2973

We’ve promoted FormField from Preview to Main. The following changes has been made to provide more flexibility and better explicit components when using inputs.

• The orientation prop on the FormField component will be updated to accept the following values: "vertical", "horizontalStart", and "horizontalEnd". "horizontal" will still be accepted as a value in v12, but it will be deprecated and slated for removal in a future major release. These changes are intended to provide more flexibility with label alignments on FormField elements.

Note: The horizontal alignment of start and end are relative to its container, meaning start and end match the flex property of flex-start and flex-end. This is especially applicable for moving between RTL (right-to-left) and LTR (left-to-right) languages.

Note: Orientation "horizontal" has been deprecated. You will see a console warn message suggesting to update your types and usage to "horizontalStart", "horizontalEnd" or "vertical".

• useFormFieldModel: orientation has been added back into useFormFieldModel. While we still support compat mode due to style merging issues, having orientation on the model allows for proper styling of sub components.

• Styles clean up: FormField.Hint and FormField.Label where using margin for spacing. We’ve updated styles so that the containing element uses gap for proper spacing.

• We’ve added a new example to our docs to showcase how our inputs can be styled in different environments like density and container alignment.

Note: If spacing seems off between the input and hint text, ensure you’re using FormField.Field wrapping your input and hint text.

Breaking API Change

The newly promoted FormField is a compound component. Due to the different APIs of the component, this change is not codemodable. The following shows an example of how to update your code to match the new compound component API.

// v11 FormField in Main
<FormField
  error={FormField.ErrorType.Alert}
  labelPosition={FormField.LabelPosition.Left}
  useFieldSet={true}
  required={true}
	inputId='input-id'
  hintId="hint-alert"
  hintText="Please enter a valid email."
  label="Email"
>
  <TextInput onChange={handleChange} value={value} />
</FormField>
 
 
// v12 Newly promoted FormField from Preview to Main
<FormField
  error="alert"
  orientation="horizontalStart"
  isRequired={true}
	id='input-id'
>
	<FormField.Label>Email</FormField.Label>
	<FormField.Field>
		<FormField.Input as={TextInput} onChange={handleChange} value={value} />
		<FormField.Hint>Please enter a valid email.</FormField.Hint>
	</FormField.Field>
</FormField>

• FormField.LabelPosition.Hidden is no longer valid. If you still want to hide the label, use the prop isHidden.

// v11 FormField in Main
<FormField
  error={FormField.ErrorType.Alert}
  labelPosition={FormField.LabelPosition.Hidden}
  useFieldSet={true}
  required={true}
  inputId="input-id"
  label="Search"
>
  <TextInput onChange={handleChange} value={value} />
</FormField>;
 
// v12 Newly promoted FormField from Preview to Main
 
//...
 
<FormField error="alert" orientation="horizontalStart" isRequired={true} id="input-id">
  <FormField.Label isHidden>Search</FormField.Label>
  <FormField.Field>
    <FormField.Input as={TextInput} onChange={handleChange} value={value} />
  </FormField.Field>
</FormField>;

Noticeable changes:

• error prop takes in the following values: "error" | "alert".
• labelPosition becomes orientation with the following values: "horizontal" | "horizontalStart" | "horizontalEnd" | "vertical".
• useFieldSet is no longer valid. If you want to group inputs, use FormFieldGroup component.
• required becomes isRequired.
• hintId is no longer needed. The component handles associating the hint text, label and input automatically. If you wish to have a unique id, you can add one onto the FormField element.
• hintText is no longer a valid prop. Use FormField.Hint sub-component.
• errorLabel and alertLabel are no longer valid props. Customize your hint text inside of FormField.Hint.
• label is no longer a valid prop. Use FormField.Label sub component to render your label text.
• Instead of rendering an input, ensure you use FormField.Input with the as prop. This ensures proper error handling and aria attributes for accessibility.
• inputId is no longer a valid prop. Use id if you want a custom id, otherwise, the component will handle generating a unique id to associate each element for accessibility.
• isHidden has been added as a prop to FormField.Label in cases where you want to hide the label while still meeting accessibility standards.

🤖 The codemod will handle the change of orientation="horizontal" to orientation="horizontalStart" if you’re using the string literal values. It will also handle updating your imports from @workday/canvas-kit-preview-react/form-field to @workday/canvas-kit-react/form-field.

Form Field Group

We’ve added a new component to the FormField package to allow users to group inputs without worrying about setting the as prop on the FormField component.

Use FormFieldGroup when you have a group of inputs that need to be associated to one another, like RadioGroup or a group of Checkbox’s.

FormFieldGroup supports the same props of FormField:

• error: "alert" | "error" Defines the error around the whole group of inputs.
• orientation: "horizontalStart" | "horizontalEnd" | "vertical" | "horizontal" . Defines the label placement.
• isRequired: true Defines if a group like RadioGroup is required.

Form Field Field

We’ve added a new sub-component to FormField and FormFieldGroup, FormField.Field and FormFieldGroup.Field. This sub-component is meant to ensure that the label is always aligned with the input regardless of the orientationprop’s value onFormField or FormFieldGroup. This component should replace FormField.Container and always be used to ensure proper alignment of the label and hint text. Our examples have been updated to reflect this.

Although there is no codemod for this change and it’s non-breaking, we suggest moving towards adding this sub-component when using FormField. This component also exists on FormFieldGroup.

<FormField orientation="horizontal">
  <FormField.Label>Email</FormField.Label>
  <FormField.Field>
    <FormField.Input as={TextInput} />
    <FormField.Hint>You must provide an email</FormField.Hint>
  </FormField.Field>
</FormField>

Menu Item

PR: 2969

Menu.Item was converted to use Stencils for styling and uses SystemIcon stencil variables to change icon color instead of deeply nested selectors. We also added Menu.Option component for menus that have a selected visual state. Menu.Option will need more accessibility affordances that depend on the nature of your use of the Menu component. For example, <Combobox> and <Select> use Menu.Option and add keyboard events and aria-* attributes to function according to w3c specifications.

We’ve deprecated the isDisabled prop. It didn’t do anything in v10 or v11. It was part of the preview Menu deprecation, but was never hooked up. We mapped it to aria-disabled and added a deprecation comment to use aria-disabled instead.

We’ve removed the MenuItemProps export from @workday/canvas-kit-react/menu. Use ExtractProps<typeof Menu.Item, never> instead. We don’t mean to export prop interfaces of polymorphic components. The never means “don’t add element props”. The second parameter is used to pass the interface that the as prop is pointing to.

Menu.Item no longer sets aria-selected since that attribute is not valid on a role=menuitem. The Menu.Option was added to support the role of a role=option for going inside a role=listbox. The Combobox family of components uses a role=listbox for menu options. The Menu.Option renders a checkmark for a visual indication of selected options.

MultiSelect

PR: 2911

Added the MultiSelect component to select more than one option from a list of options. The MultiSelect is similar in API to the Select component, except the values are comma delimited with a space. If the ids represented are ['1', '2'], then the string value of the form field is '1, 2'.

Search Form (Labs)

PRs: #2934,

SearchForm is now using the newly promoted FormField component. SearchForm now uses labelId to set the appropiate aria attributes and id on the underlying input element.

Select

PRs: #2865, #2983

As we transition to use our CSS tokens to provide better theming capabilities and our new styling methods, we’re moving away from components extending Themeable. Themeable has been removed from SelectProps.

If you wish to theme Select we suggest using the CanvasProvider to do so.

const theme: PartialEmotionCanvasTheme = {
  canvas: {
    palette: {
      common: {
        focusOutline: 'pink',
      },
      primary: {
        main: 'green',
        light: 'lightgreen',
      },
    },
  },
};
 
//...
 
<CanvasProvider theme={theme}>
  <Flex cs={parentContainerStyles}>
    <Select items={options}>
      <FormField>
        <FormField.Label>Contact</FormField.Label>
        <FormField.Input as={Select.Input} onChange={handleChange} />
        <Select.Popper>
          <Select.Card>
            <Select.List>
              {item => {
                return <Select.Item>{item}</Select.Item>;
              }}
            </Select.List>
          </Select.Card>
        </Select.Popper>
      </FormField>
    </Select>
    Selected Value: {value}
  </Flex>
</CanvasProvider>;

Select has been refactored to use useComboboxInputConstrained to sync the model and the input element regardless of the source. This makes the Select a controllable component.

Text Area

PR: #2825

TextAreaResizeDirection is no longer a TypeScript enum, but a JavaScript object. This change does not effect runtime at all, but may cause TypeScript errors if you use TextAreaResizeDirection as a type.

// v11
interface MyProps {
  resize?: TextAreaResizeDirection;
}
 
// v12
type ValueOf<T> = T[keyof T];
interface MyProps {
  resize?: ValueOf<typeof TextAreaResizeDirection>;
}

Themeable has been removed from TextAreaProps. If you wish to theme TextArea, use our CanvasProvider with the theme object.

const theme: PartialEmotionCanvasTheme = {
  canvas: {
    palette: {
      common: {
        focusOutline: 'pink',
      },
      primary: {
        main: 'green',
        light: 'lightgreen',
      },
    },
  },
};
 
//...
 
<CanvasProvider theme={theme}>
  <FormField>
    <FormField.Label>Contact</FormField.Label>
    <FormField.Input as={TextArea} onChange={handleChange} />
  </FormField>
</CanvasProvider>;

Text Input

PR: #2825

Themeable has been removed from TextInputProps. If you wish to theme TextInput, use our CanvasProvider with the theme object.

const theme: PartialEmotionCanvasTheme = {
  canvas: {
    palette: {
      common: {
        focusOutline: 'pink',
      },
      primary: {
        main: 'green',
        light: 'lightgreen',
      },
    },
  },
};
 
//...
 
<CanvasProvider theme={theme}>
  <FormField>
    <FormField.Label>Contact</FormField.Label>
    <FormField.Input as={TextInput} onChange={handleChange} />
  </FormField>
</CanvasProvider>;

Collections

PR: #2982

The navigation.getItem() function can now return undefined instead of throwing an error when an item is not found. Throwing an error caused lots of problems when it came to dynamic data. This is a breaking change if your application uses getItem. It will now have to deal with the possibility of an undefined.

Utility Updates

PR: #2908

mergeProps

mergeProps had a bug where sometimes the returned props would be never. Also mergeProps would not narrow types which would require you to add as const. We fixed the type signature to more accurately reflect how mergeProps works. This may catch new type errors not caught before. There is no way to codemod this. Let us know if you need help fixing new type errors introduced by this change.

More information: https://github.com/Workday/canvas-kit/discussions/2979

createElemPropsHook

createElemPropsHook now uses const Type Parameters to narrow types in the object. This prevents requiring as const in some situations. This alone should fix bugs instead of introduce them.

More information: https://github.com/Workday/canvas-kit/discussions/2979

composeHooks

composeHooks uses mergeProps and suffered the same bugs. If any hook in the composeHooks chain used a null prop, the entire prop object returned was typed as never. This caused a bug where if the Component required a prop, it wasn’t being provided by the composed hook. Some of our components manually added to the component’s prop interface so the component’s render function wouldn’t complain. This has been fixed. This may be a breaking change where before the spread elemProps was never, so no type conflicts could exist with component props. Now all props are properly represented which may mean TypeScript is now catching bugs it didn’t before.

More information: https://github.com/Workday/canvas-kit/discussions/2979

Troubleshooting

My Styles Seem Broken?

Our components are reliant on our new Canvas Tokens Web package. Be sure to install @workday/canvas-tokens-web. For more information, reference our Getting Started docs for this package.

Did You Upgrade All Canvas Kit Related Packages?

In order for all the packages to work in harmony, you must upgrade all Canvas Kit packages to the same version that you’re using, including:

• @workday/canvas-kit-react
• @workday/canvas-kit-preview-react
• @workday/canvas-kit-labs-react
• @workday/canvas-kit-styling
• @workday/canvas-kit-react-fonts
• @workday/canvas-kit-docs

Glossary

Main

Our Main package of Canvas Kit tokens, components, and utilities at @workday/canvas-kit-react has undergone a full design and a11y review and is approved for use in product.

Breaking changes to code in Main will only occur during major version updates and will always be communicated in advance and accompanied by migration strategies.

Preview

Our Preview package of Canvas Kit tokens, components, and utilities at @workday/canvas-kit-preview-react has undergone a full design and a11y review and is approved for use in product, but may not be up to the high code standards upheld in the Main package. Preview is analagous to code in beta.

Breaking changes are unlikely, but possible, and can be deployed to Preview at any time without triggering a major version update, though such changes will be communicated in advance and accompanied by migration strategies.

Generally speaking, our goal is to eventually promote code from Preview to Main. Occasionally, a component with the same name will exist in both Main and Preview (for example, see Segmented Control in Preview and Main). In these cases, Preview serves as a staging ground for an improved version of the component with a different API. The component in Main will eventually be replaced with the one in Preview.

Labs

Our Labs package of Canvas Kit tokens, components, and utilities at @workday/canvas-kit-labs-react has not undergone a full design and a11y review. Labs serves as an incubator space for new and experimental code and is analagous to code in alpha.

Breaking changes can be deployed to Labs at any time without triggering a major version update and may not be subject to the same rigor in communcation and migration strategies reserved for breaking changes in Preview and Main. import { opacity } from "@workday/canvas-tokens-web/dist/es6/system"

Getting started

This upgrade grade goes over changes to Canvas Figma libraries as well as instructions for upgrading to Canvas v12.

Deciding When To Upgrade

With versioned Canvas Web Figma libraries, designers can be on the same version of Canvas as their developers. Designers should work with their developers to align on the version that should be used in design and code. Using the same Canvas version across design and code helps promote a smooth design to development handoff process by ensuring that:

• The same components are available in both Figma and code
• Component styles are consistent across Figma and code

We recommend chatting with your wider team to understand what version they are currently building with, and when they plan to upgrade to the next version of Canvas. For some teams this could take a few days, for others it could be weeks. Setting an upgrade date will help keep the team on the same page.

Preparing for the Upgrade

There are things that can be done before upgrading to v12 that may streamline the process and save time.

Identify Key Files for the Upgrade

Mark the covers of the files that should be upgraded to Canvas Web v12. This helps your team identify which files are actively being maintained and which should be archived. To reduce the time spent resolving breaking changes, it’s recommended that the saved files are kept to the core screens in the experience. These core screens can then be updated to handle breaking changes allowing you to continue to work on future designs while removing clutter. All previous designs may be archived if you need to reference these in the future.

Back Up Key Files

Before upgrading, consider backing up your current version through a branch.

Update the Current Version

Before upgrading to Canvas Web v12, make sure to accept any changes in Canvas Web v11.

Create a Branch of the Main File (Recommended)

Branching saves a version of your current file and creates a separate space to upgrade. Merging back to main will show the before and after, as well as any diffs.

Duplicate Key Files

Alternatively, you can duplicate essential files and upgrade those, indicating the Canvas version for clarity.

Making the Upgrade

1. Go to your Figma file
2. Accept any library updates
3. Create a Figma branch named “Upgrade to v12”
4. Navigate to the Upgrade to v12 branch
5. Go to active libraries (option + 2)
6. Locate the Canvas Web v11 library
7. Library swap Canvas Web v11 with Canvas Web v12
8. Merge the branch back into the main file
9. Review visual differences before accepting merge

Canvas Tokens v2

No changes have been made to the Canvas Tokens v2 library.

Changes in Canvas Web v12

Features

New Multi Select Component

A new MultiSelect component has been added to Canvas v12. MultiSelect is a selection input where one or multiple items may be selected.

This component will be available for use once designers turn on the Canvas Web v12 library.

New Form Field Component

A new FormField component is available in Canvas v12. FormField is a generic wrapper for Input components that makes them accessible for Forms. We recommend using Form Field to easily switch between different input types.

This component will be available for use once designers turn on the Canvas Web v12 library.

New End Alignment Property for Input labels

A new end alignment variant is available for use on all input components. This includes: Text Input, Text Area, Select, Multi-Select, Checkbox, Checkbox Group, Radio Group, Color Preview, and Color Input. For these inputs, the label property can be set to the following: top, start, end , none.

The new end alignment variant will be available for the input components listed above once users swap over to the new Canvas Web v12 Figma library, but will not impact existing designs as it is a net-new feature.

New Text Property for Input Containers

A new text property is available for text within input containers. This will allow designers to edit text within an input container through the Figma panel on the right hand side and will be available for Text Input, Text Area, and Select.

This feature will be available once users swap over to the Canvas Web v12 Figma library. Designs will not be impacted as existing text within input containers will be preserved.

Enhancements

Dialog and Modal Refactoring

Autolayout and breakpoint tokens have been applied to Dialog and Modal, enabling adaptive behavior through Figma variable modes. Dialog and Modal will swap between desktop and mobile variants based on the size of the parent frame.

These changes will be automatically applied once users swap over to the Canvas Web v12 Figma library and will not impact existing designs.

Menu Item Selection State Update

An updated selected state has been applied to the menu item in the standalone Menu component. Changes include an updated foreground color and checkmark icon placed after menu item text.

This change will be applied automatically once users swap over to the Canvas Web v12 Figma library. Existing designs will be updated to reflect the new selected state.

Input Components Layer Restructuring

The layer structure for all Canvas input components have been restructured to be consistent from input to input. Shared component properties (ex: labels, states) are now aligned, enabling the properties to be preserved when swapping between various inputs.

These changes will be automatically applied once users swap over to the Canvas Web v12 Figma library and will not impact existing designs.

Component Refactoring to use Brand and System Tokens

The following components have been refactored to use System and Brand Tokens: Text Input, Text Area, Toast, and Avatar. These changes will be automatically applied once users swap over to the Canvas Web v12 Figma library and will not impact existing designs.

Adjustable Top and Bottom Padding for Input Containers

To support changes in Forms Framework, top and bottom padding may be adjusted via Canvas tokens within the Input layer for all form elements. These changes will be automatically applied once users swap over to the Canvas Web v12 Figma library and will not impact existing designs.

Deprecations

Expanded Select Menu Deprecation

The expanded Select Menu is deprecated in Canvas v12. Users should use the standalone Menu component instead, which will enable designers to more easily customize and swap between different Menu variants.

This update will not impact existing designs, but deisgners should swap over to the standalone Menu component before this component is removed.

Menu Icon Variant Deprecation

The icon variant for the standalone Menu component is deprecated in Canvas v12.

This update will not impact existing designs and no action is required at the moment, but a new icon property will be introduced by the time the Menu icon variant is fully removed to support icons usage within Menu.

Canvas Web v9 Library Deprecation

The Canvas Web v9 Figma library will be deprecated and moved to the Archive folder. Design files using this library will not be impacted.