No Preview

Sorry, but you either have no stories or none are selected somehow.

If the problem persists, check the browser console, or the terminal you've run Storybook from.

Vibe 3 Migration Guide

Intro

Vibe 3 is a major update to the Vibe design system, introducing several new features, enhancements, and breaking changes. This guide will walk you through the changes to help you transition smoothly from v2 to v3.

Migration from v1 to v2

To migrate from v1 to v2, please refer to the Vibe 2 migration guide

New Features ✨

Package rename

The monday-ui-react-core package has been renamed to @vibe/core to better reflect the library's purpose and align with the Vibe branding. In addition, the /icons entry point has been moved to a new @vibe/icons package.

packages split diagram

Reduced bundle size

By removing CommonJS support, dividing the library into packages, and optimizing the library exports - the bundle size has been reduced by 43%, resulting in faster load times and improved performance.

New Typography System

New and improved Heading, EditableHeading components. For more info, check the Typography section.

Enhanced Typescript Support

All components' types and interfaces are exported for better type-safe compositions. For example:

import { Button, ButtonProps, ButtonSize } from "@vibe/core";

Improved prop type-checking

Now you can use type-safe strings instead of static enums for props, providing a better and faster development experience:

// Before <Button kind={Button.kinds.PRIMARY} size={Button.sizes.SMALL}>click</Button> // After <Button kind="primary" size="small">click</Button>

See IntelliSense in action in your favorite IDE:

Using props values instead of enums

You can keep using the static properties, although not recommended, as they are likely to be deprecated in the future.

Improved layering of floating components

When used inside Modals, the floating components (i.e., Tooltip, Tipseen, Dialog) will now be rendered inside the Modal's container by default, ensuring they are always on top. This change prevents any z-index interference and ensures a consistent user experience.

floating elements on modal

Migration Steps 🚀

Most of the changes required to migrate from Vibe 2 to Vibe 3 are covered by an automatic migration script, but some manual changes may still be required, especially changes that are related to style, UX, or behavior.

These steps will guide you through the migration process:

  1. Install @vibe/core (and @vibe/icons, if needed) and remove monday-ui-react-core:

    yarn add @vibe/core @vibe/icons # or npm install @vibe/core @vibe/icons yarn remove monday-ui-react-core # or npm uninstall monday-ui-react-core

    The changes in your package.json file should look like this:

    "dependencies": {
    - "monday-ui-react-core": "^2.120.0",
    + "@vibe/core": "^3.0.0",
    + "@vibe/icons": "^1.0.0"
      ...
    },
  1. Run the migration script to update your codebase:

    npx @vibe/codemod -m v3

    For more information, and for more options, refer to the @vibe/codemod docs.

  2. Follow the changes in the Breaking Changes 🚨 section below and apply any manual changes required.

  3. Review the changes and test your application thoroughly to ensure everything works as expected.

  4. Run Prettier or any code formatting tool to format the changes made by the migration script [optional].

Breaking Changes 🚨

Several breaking changes have been made to optimize and streamline the library. These changes include the removal of deprecated components, updates to component APIs, and overall enhancements.

Please note that the following changes are complementary to the migration script and require manual intervention, assuming that the migration script has ran successfully. If you prefer migrating entirely manually (without the @vibe/codemod script), please refer to the Complete Vibe 3 changelog.

General

  • CommonJS support has been removed to modernize the library, reduce complexity, and ensure better compatibility with modern JavaScript tooling and ESM (ECMAScript Modules) standards.
  • The monday-ui-react-core/storybookComponents entry was removed, use the vibe-storybook-components package instead.
  • The monday-ui-react-core/dist/main.css was removed, use @vibe/core/tokens instead to load all relevant CSS tokens:
    - import "monday-ui-react-core/dist/main.css";
    + import "@vibe/core/tokens";
    
  • The monday-ui-style/src/Icons was removed, use @vibe/icons/raw instead to use svg icons:
    - import Close from "monday-ui-style/src/Icons/Close.svg";
    + import { Close } from "@vibe/icons/raw";
    

Typography

The typography system has been updated to provide a more consistent and accessible experience. The new typography system includes a set of predefined text styles and sizes that can be easily applied to components.

  • Use the Text component for paragraphs, labels, and texts up to 16px. It includes 3 variants: text1, text2 and text3. Each variant has a fixed size and three different weights.

  • Use the Heading component the for titles and text from 18px and up. It includes 3 variants: h1, h2 and h3. Each of these variant is mapped to an h1, h2, h3 element accordingly.

To replace old typography usages:

  • H1 Main heading (--font-h1) → Heading/H1/normal
  • H2 Secondary heading (--font-h2) → Heading/H2/bold
  • H3 Tertiary heading (--font-h3) → Heading/H2/light
  • H4 Fourth heading (--font-h4) → Heading/H3/bold
  • H5 Paragraph (--font-h5) → Text/text1/bold
  • H6 UI text (--font-general-label) → Text/text2/normal
  • Medium Text (--font-subtext) → Text/text2/normal
  • P Paragraph text (--font-paragraph) → Text/text1/normal
  • Medium text link (--font-general-label, --link-color) → Text/text2/normal

For more information, refer to the Typography docs.

Components

The following components have been removed and are no longer available:

These components were rewritten from scratch with new API and style, offering better accessibility and usability:

Make sure to import them from @vibe/core instead of the /next entry:

- import { Heading, EditableHeading, Search } from "monday-ui-react-core/next";
+ import { Heading, EditableHeading, Search } from "@vibe/core";

The following components have breaking changes to their API, behavior, or style, as detailed below:

AvatarGroup

  • The component no longer has padding at the bottom

Button

  • The children prop is now required
  • The sm, md, lg sizes were removed, use small, medium, large respectively:
    - <Button size="sm">
    + <Button size="small">
    

Chips

  • The DARK_INDIGO and BLACKISH colors were removed from the color prop
  • The clickable and isClickable props were removed, use onClick instead, to get clickable behavior and style:
    - <Chips clickable>
    + <Chips onClick={() => {}}>
    

Counter

  • The sm, md, lg sizes were removed, use small, medium, large respectively:
    - <Counter size="sm">
    + <Counter size="small">
    

DialogContentContainer

  • The "medium" size now has an increased padding, correcting a previous sizing issue where "medium" and "small" had identical paddings. As a result, "small" is now the default size. If no size was specified there's no action required.

Flex

  • The Flex.gaps.NONE property has been removed. To specify no gap simply omit the gap prop

Dropdown

  • The xxs, xs sizes were acting as the small size and were therefore removed. Use small instead
  • New readonly style

Icon

  • The clickable, onClick props were removed, use <IconButton> for clickable icons:
    - <Icon icon={Heart} clickable onClick={() => {}}>
    + <IconButton icon={Heart} onClick={() => {}}>
    

Label

  • The "Spin In" animation was removed

MenuButton

  • The hideWhenReferenceHidden prop default value changes to "true", meaning when the MenuButton is hidden hide the dialog and tooltip as well. To disable this behavior set hideWhenReferenceHidden to "false"

MenuItem

  • The provided tooltip (when the text is overflowing) now wraps the entire element so non-block layout given to the title prop may break

Modal

  • The hideCloseButton has been removed since Modals should always have a close button. It has also been removed from ModalHeader component.
  • The unmountOnClose prop default value changes to "true", meaning the Modal will not render when show is "false". To disable this behavior set unmountOnClose to "false"
  • Tooltips, Tipseens, and Dialogs on Modals will now be rendered inside the Modal's container by default, without any z-index interference

SplitButton

  • The data-testId prop will no longer be applied to the internal elements, only the root element

Steps

  • The isOnPrimary prop was removed, use color="primary instead:
    - <Steps isOnPrimary>
    + <Steps color="primary">
    

Tabs

  • The browser's default margin/padding for ul and li elements were reset

TabList

  • The component no longer gets a padding bottom

TabPanels

  • TabPanels will render only the active tab instead of rendering all the panels

TextField

  • The iconsNames prop no longer accepts the layout property
  • Providing the required prop will now show a red asterisk, implying that the field is mandatory, and so the requiredAsterisk prop was removed
  • New readonly style
  • The sm, md, lg sizes were removed, use small, medium, large respectively:
    - <TextField size="sm">
    + <TextField size="small">
    

Tipseen

  • The content prop is now mandatory
  • The default color has changed from 'primary' to 'inverted'. To keep the previous color, set the color prop to 'primary'
  • The showDelay prop's default value has changed to 100
  • The justify prop was removed, and so the Tipseen.justifyTypes static property was removed as well

TipseenContent

  • The submitButtonProps, dismissButtonProps props were removed, use submitButtonText and dismissButtonText to change the buttons' text

Tooltip

  • The paddingSize, justify, and arrowPosition props were removed. Accordingly the Tooltip.paddingSizes, Tooltip.justifyTypes, and Tooltip.arrowPositions static properties were removed as well
  • The theme prop can now accept only "dark" or "primary"
  • The position prop can now accept only "top, right, bottom, left"
  • The showOnDialogEnter prop's default value has changed to true; now the tooltip will remain open by default when hovering over it
  • The hideDelay prop's default value changed to 100
  • The addKeyboardHideShowTriggersByDefault default changed to true, making it accessible with keyboard navigation
  • The tooltip's max-width is now set to 240px
  • The Tooltip's content is now wrapped in another div, meaning that non-block layouts inside the tooltip may break
  • The containerSelector will now fallback to document.body instead of #tooltips-container if not provided

Colors

  • The --shareable-color and --private-color CSS variables were removed for all themes
  • The color-warning, color-warning-hover, color-warning-select, color-warning-select-hover colors were removed from the colors.json file (in monday-ui-style package), use warning-color-* respectively

Icons

  • The Upgrade icon has been removed, and the Featured icon has been renamed to Upgrade:
  • The Replay icon has been renamed to Reply
    - <Icon icon={Featured}>
    + <Icon icon={Upgrade}>
    

FAQ ❓

What is the best way to migrate to Vibe 3?

It is recommended to follow the migration steps outlined in this guide to ensure a smooth transition from Vibe 2 to Vibe 3.

Are there any manual changes required after running the migration script?

While the migration script covers most changes, some manual changes may still be required where style, UX, or behavior changes are involved. You should walk through the breaking changes section to identify any manual changes required.

Do I need to stop using static properties (e.g. Button.kinds.PRIMARY) in my code?

You can still use static properties, but it is recommended to use type-safe strings instead. Static properties are likely to be deprecated in the future. To migrate to type-safe strings, use the following script: npx @vibe/codemod -m enums.

I have already been using Heading, EditableHeading, Search from /next, do I need to change anything?

If you have been using these components from /next, you will only need to update your imports to use the components from the main entry (@vibe/core).

Are there any known issues or limitations with Vibe 3?

While we have made every effort to ensure Vibe 3 is stable and reliable, there may be some known issues or limitations. If you encounter any problems, please create an issue.

What if I don't want to migrate to Vibe 3?

While we recommend migrating to Vibe 3 to take advantage of the new features and improvements, you can continue using Vibe 2. However, please note that Vibe 2 will no longer recieve any new features or updates aside from critical bug fixes, and will reach EOL upon the next major version (Vibe 4) release.

The migration script failed to run, what should I do?

Make sure to run the migration script in the root directory of your project, and make sure to run it on a clean git branch to avoid any conflicts. If you still encounter issues, please create an issue describing the steps, system info and any error messages you received.

Help 🙏

If you have any questions, feedback, or need help, please don't hesitate to reach out to us. You can provide feedback or report issues in the Vibe repository on GitHub.