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 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.
To migrate from v1 to v2, please refer to the Vibe 2 migration guide
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.
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 and improved Heading, EditableHeading components. For more info, check the Typography section.
All components' types and interfaces are exported for better type-safe compositions. For example:
import { Button, ButtonProps, ButtonSize } from "@vibe/core";
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:
You can keep using the static properties, although not recommended, as they are likely to be deprecated in the future.
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.
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:
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"
...
},
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.
Follow the changes in the Breaking Changes 🚨 section below and apply any manual changes required.
Review the changes and test your application thoroughly to ensure everything works as expected.
Run Prettier or any code formatting tool to format the changes made by the migration script [optional].
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.
monday-ui-react-core/storybookComponents
entry was removed, use the vibe-storybook-components package instead.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";
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";
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:
--font-h1
) → Heading/H1/normal--font-h2
) → Heading/H2/bold--font-h3
) → Heading/H2/light--font-h4
) → Heading/H3/bold--font-h5
) → Text/text1/bold--font-general-label
) → Text/text2/normal--font-subtext
) → Text/text2/normal--font-paragraph
) → Text/text1/normal--font-general-label
, --link-color
) → Text/text2/normalFor more information, refer to the Typography docs.
The following components have been removed and are no longer available:
Input
- use TextField insteadEditableInput
- use EditableText insteadSearchComponent
- use Search insteadResponsiveList
- use useIsOverflowing hook instead, to show/hide content based on overflowThese 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
Button
children
prop is now requiredsm
, md
, lg
sizes were removed, use small
, medium
, large
respectively:- <Button size="sm">
+ <Button size="small">
Chips
DARK_INDIGO
and BLACKISH
colors were removed from the color
propclickable
and isClickable
props were removed, use onClick
instead, to get clickable behavior and style:- <Chips clickable>
+ <Chips onClick={() => {}}>
Counter
sm
, md
, lg
sizes were removed, use small
, medium
, large
respectively:- <Counter size="sm">
+ <Counter size="small">
DialogContentContainer
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
Flex.gaps.NONE
property has been removed. To specify no gap simply omit the gap
propDropdown
xxs
, xs
sizes were acting as the small
size and were therefore removed. Use small
insteadIcon
clickable
, onClick
props were removed, use <IconButton>
for clickable icons:- <Icon icon={Heart} clickable onClick={() => {}}>
+ <IconButton icon={Heart} onClick={() => {}}>
Label
MenuButton
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
title
prop may breakModal
hideCloseButton
has been removed since Modals should always have a close button. It has also been removed from ModalHeader component.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"SplitButton
data-testId
prop will no longer be applied to the internal elements, only the root elementSteps
isOnPrimary
prop was removed, use color="primary
instead:- <Steps isOnPrimary>
+ <Steps color="primary">
Tabs
ul
and li
elements were resetTabList
TabPanels
TextField
iconsNames
prop no longer accepts the layout
propertyrequired
prop will now show a red asterisk, implying that the field is mandatory, and so the requiredAsterisk
prop was removedsm
, md
, lg
sizes were removed, use small
, medium
, large
respectively:- <TextField size="sm">
+ <TextField size="small">
Tipseen
content
prop is now mandatorycolor
has changed from 'primary' to 'inverted'. To keep the previous color, set the color
prop to 'primary'showDelay
prop's default value has changed to 100justify
prop was removed, and so the Tipseen.justifyTypes
static property was removed as wellTipseenContent
submitButtonProps
, dismissButtonProps
props were removed, use submitButtonText
and dismissButtonText
to change the buttons' textTooltip
paddingSize
, justify
, and arrowPosition
props were removed. Accordingly the Tooltip.paddingSizes
, Tooltip.justifyTypes
, and Tooltip.arrowPositions
static properties were removed as welltheme
prop can now accept only "dark" or "primary"position
prop can now accept only "top, right, bottom, left"showOnDialogEnter
prop's default value has changed to true
; now the tooltip will remain open by default when hovering over ithideDelay
prop's default value changed to 100addKeyboardHideShowTriggersByDefault
default changed to true, making it accessible with keyboard navigationcontent
is now wrapped in another div
, meaning that non-block layouts inside the tooltip may breakcontainerSelector
will now fallback to document.body
instead of #tooltips-container
if not provided--shareable-color
and --private-color
CSS variables were removed for all themescolor-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-*
respectivelyUpgrade
icon has been removed, and the Featured
icon has been renamed to Upgrade
:Replay
icon has been renamed to Reply
- <Icon icon={Featured}>
+ <Icon icon={Upgrade}>
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.
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.