npm / element-plus
element-plus
What changed in element-plus 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
10 breaking79 new APIs and options2 performance48 behavior and defaults2 tooling237 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initelement-plus 2378 changes
Breaking changes 10
Date picker removes keyboard navigation for quarters.
Removes el-teleport.
The menu-item index attribute is now required.
Removing a split now removes the whole input containing it.
The color-picker-panel showAlpha default is now false.
Stops the change event from bubbling.
The date-picker-panel removes the pick emit declaration.
The select and select-v2 dropdown no longer closes on mixed input.
The project upgrades to Vue 3.5.
Handles keyboard input on keydown.
New APIs and options 79
The text component exposes isTruncated.
Theme-chalk exposes a form item margin bottom variable.
Date picker adds a quarter picker.
Adds the pauseOnHover option to notifications.
Adds the progress option to notifications.
The table component adds the getHalfSelectionRows method.
Adds a popper-options prop.
Adds a show-arrow prop.
Adds fitInputWidth support.
Adds height support.
Adds item-size support.
Adds virtual-scroll support.
Adds the singlePanel prop for range-picker.
Adds a formatter prop.
Adds a parser prop.
Adds a tabindex prop.
Adds a new input-otp component.
Adds an end-reached event to select and select-v2.
Buttons support custom color with link and text variants.
Input adds grapheme counting.
Input exposes passwordVisible.
The color picker panel adds hue-slider-class and hue-slider-style props for customizing the hue slider.
The input component adds a password-icon slot.
The slider step can be set to "mark".
Textarea supports inputmode.
Popover exposes hide() through its slot.
Adds the save-on-blur prop to time-picker.
The button component adds a
dashedprop.The time-select component adds a
nameprop.A
setPropsDefaultsutility method is added.Config provider adds table configuration.
Select and select-v2 add a
tag-tooltipconfig object prop.The
requireNodeKeyargument is included inupdateKeyChildren.DrawerInstance is exposed for use by developers.
The table component adds the row-expandable prop.
A type for TimePickerInstance is added.
Adds the avatar-group component.
Adds the controller-type prop to calendar.
Adds the formatter prop to calendar.
Adds a clear event for handling color-picker clearing.
Adds the clearable prop so developers can enable clearing the color picker.
Adds the icon slot to dropdown-item.
Adds the setInitialValue function.
Adds the setInitialValues function.
Adds the cancelButtonType prop.
Adds the confirmButtonType prop.
Adds the mode prop to timeline.
Adds the directory prop to upload.
The switch component adds an active slot.
The dropdown component adds append-to support for choosing where its content is appended.
The affix component supports append-to.
The switch component adds an inactive slot.
The affix component supports teleported.
Adds a direction prop to button-group.
Adds a $space parameter to the theme-chalk channel function.
Adds the remote-show-suffix prop.
Exposes splitterPanelRef for accessing a splitter panel.
Adds a default-value prop to tabs, suppressing flicker.
Adds a reverse prop to timeline.
Adds an instance type for tree-select.
Exposes a blur method on cascader.
Exposes a focus method on cascader.
Adds the resize event to drawer.
Adds the resize-end event to drawer.
Adds the resize-start event to drawer.
Adds debounce prop support to select and select-v2.
Select supports Home and End key events.
Adds the modal-penetrable prop to drawer.
Adds the tabindex prop to tabs.
Adds the validateEvent prop to color-picker-panel.
Adds a supplementary type for DatePickerInstance.
Checkbox-group supports options with el-checkbox-button.
Radio-group supports options with el-radio-button.
The watermark component adds the fontGap prop.
Cascader lazyLoad supports rejection.
Input adds the modelModifiers prop.
Mention, menu, dropdown, and pagination add popper-style support.
Supports uneven step sizes.
Input adds word-limit-position attributes.
Performance 2
Adds virtual scroll support to the Transfer component.
Avoids duplicate rendering after props change.
Behavior and default changes 48
Adds a grab cursor to the image viewer.
Multiple table filters are deferred until confirmation.
Form-item validation messages now have the alert role.
Input exposes the word limit count to screen readers.
Emits the change event when password visibility is toggled.
Omits the gpuAcceleration default value.
Includes popup lockscreen styles when importing drawer styles.
Tabs support scrolling via touch.
Removes trailing inline margin.
Passes action-handlers to the vnode.
Supports deep checking in tree, tree-v2, and tree-select.
Style properties now support Boolean values.
A clicked dialog is brought to the front.
Autocomplete is made generic.
Mention is made generic.
Transfer is made generic.
The segmented component is now generic.
Navigation wheel scrolling experience is improved.
The input clear event now passes the event parameter.
Textarea supports clearing effects.
FormRules now supports nested rules.
DOM utilities now support ShadowDom.
Toggling node labels now emits a change event.
The upload abort parameter is now optional.
The table type no longer requires tableLayout.
Updates dark theme color variables for consistency.
Applies popper-options to the tag tooltip.
Adds a transition to the radio inner element.
The table-column border shadow is removed.
The table-v2 component receives accessibility enhancements.
Allows the card body height to grow.
The disabled value of a component takes the highest priority.
Disables page scrolling while a dialog is open.
Applies popper-class to the tooltip of a menu title.
Applies popper-style to the tooltip of a menu title.
The table receives an accessibility enhancement.
Loads data only when a row is expanded.
Updates link styles for hover and focus states.
Adds touch event support on mobile.
With multiple selection, locates the most recently selected option.
For multiple selection, hoveringIndex stays on the most recently selected option.
For multiple selection, hoveringIndex stays on the most recently selected option.
Allows using Numpad Enter to select an option.
Adds touch event handling for scrolling.
DatePicker allows a plain array for modelValue.
Makes the debounce prop reactive in Cascader and Autocomplete.
Autocomplete supports Home and End key events.
Makes the resizable prop reactive.
Tooling 2
Adds slot typings for table-v2.
Improves emit type hints.
Fixes and other changes 237
Avoids triggering the change event twice when clearing the time picker.
Select v2 avoids circular tag width calculation.
Upload preserves paths for dropped directories.
Date pickers prevent duplicate keyboard handling.
Fixes a memory leak in loading.
The form avoids a warning when label width is zero.
Textarea autosize no longer resets scroll in Firefox.
Tree-v2 synchronizes checked state after clearing keys.
The date picker keeps disabled-date reactive in panels.
Select now matches the input wrapper transition.
Fixes the loading spinner jiggling issue on Chrome.
Fixes tab flicker when the SSR environment sets the default value.
Clears stale suggestions when the component is refocused.
Corrects the input time format.
Prevents box-shadow noise.
Avoids an innerHTML and children conflict.
Updates the component on transition and animation end.
Prevents box-shadow noise.
Clones the spacer vnode.
Stops mutating the parent's filtered-value.
Avoids null theadRef access after the header is unmounted.
Stabilizes file list reorder transitions.
Stops repeat-click behavior after mouseup.
Fixes the field line-height.
Inherits the form size.
Correctly validates date ranges that span across years.
Avoids sticky hover on touch devices.
Hides the empty input-wrapper only when multiple.
Guards invalid time values.
Ensures the current prop is controlled when passed.
Allows falsy current keys.
Prevents duplicate root lazy-load calls.
Preserves a zero zIndex value.
Prevents the date picker panel from applying a range before it is ready.
The date picker panel honors disabledDate on an adjusted range.
Fixes iOS click listening.
Refreshes the truncated title after layout changes.
Respects check-strictly on lazy load.
Gets the current key before a node click.
Hides the buttons container when both buttons are hidden.
Improves the table component's emits type.
The table component is generic, improving type support for table usage.
Corrects the boundary when resizing the window.
Prevents layout shift when toggling the clear icon.
Avoids border flicker while resizing.
Corrects icon and count positioning when resizing textarea.
Fixes missing content wrapper in VNode messages.
Corrects background position after options change.
Correctly displays selected labels after options change.
Fixes expanding a panel with an initial size of zero.
Prevents stale height callbacks.
Fixes parent-child selection mismatch in tree data.
Fixes missing type declarations in tree-v2.
Fixes lost reactivity for scrollbar-always-on in virtual-list.
Cascader triggers before-filter when the query is empty.
Prevents ArrowDown from selecting the first leaf node.
Checkbox resets its selection state when model is null.
Fixes a TypeScript error when using csstype.
Form resets stale props on dynamic fields.
Build is compatible with generic components.
Fixes anomalous message offset positioning.
Fixes incorrect boundary detection for floating-point numbers.
Scrollbar synchronizes offsets during resize.
Prevents modified mousedown from closing select/v2 on blur.
Fixes lingering row background when table layout changes.
Allows clearing time with the keyboard when using is-range.
Avoids using window during server-side rendering.
Popover style now updates when the content size changes.
Using the options prop no longer causes list data loss when switching quickly between dropdowns.
The dropdown is no longer hidden when options contains data.
Empty labels are allowed when persistent is false.
Boundary detection is corrected when the container size is a floating-point number.
Expanded rows can now be updated using array methods.
Boundary detection is corrected when the container size is a floating-point number.
An icon in a slot no longer causes text wrapping.
Visible state now synchronizes after the tooltip is toggled disabled.
Expanded state now updates when defaultExpandedKeys changes.
Abnormal state during Korean input composition is fixed.
Reconciles parent states when setCheckedKeys is used.
Fixes an infinite loop caused by updated logic.
Resets
ignoreFocusEventon outside click.Fixes the dot becoming a rectangle during transition leave.
Carousel autoplay no longer stops after children change.
Fixes vertical indicator layout when labels and outside placement are used.
Adds validation for the color picker
colorFormatprop.A disabled rate component no longer captures focus.
Fixes form-item initial value and reset behavior.
Fixes delimiter handling for pasted line breaks.
Pressing Enter no longer selects disabled mention items.
Fixes cross-type behavior for
MessageBoxData.Fixes the default slot being invoked outside of render.
Prevents empty input from causing unnecessary line breaks in select and select-v2.
The input is always cleared after creating an option.
Trackpad scrolling no longer triggers navigation back.
Fixes unexpected page scrolling while typing in Firefox.
Fixes duplicate end times when a format is set.
Prevents the time-select component from freezing when a step is invalid.
Prevents the transfer title from overflowing its width.
Fixes a focus error after switching trees.
The upload delete icon remains visible on focus-within.
Upload appends all values in FormData.
Vietnamese translations are refined and missing keys are filled.
Corrects the watermark
fontWeighttype definition.Fixes affix positioning when using the KeepAlive cache.
Adds the missing default value for badgeStyle.
Ensures card height works correctly in a flex layout.
Adds the missing box-sizing style.
Fixes week-start selection offset and makes the startDate reliable.
Disabled buttons receive the missing is-disabled class when unlink-panels is used.
Corrects the tooltip theme and collapsed-tag styling.
Enter-key handling now accounts for IME composition, and the type definitions are corrected.
Fixes abnormal display when modelValue exceeds max.
Fixes the dropdown requiring two clicks to open.
Avoids triggering multiple visible-change events during the first search.
Fixes the dropdown requiring two clicks to open.
Avoids triggering multiple visible-change events during the first search.
Changing srcSet now resets hasLoadError on the avatar.
Fixes webkitdirectory="false" being preserved during hydration.
Fixes an empty slot being incorrectly detected as hasDesc.
Fixes an incorrect aria-controls value.
Fixes body width not being restored correctly by use-lockscreen.
Fixes scrolling to the wrong active node.
Fixes tags covering the prefix slot content.
Fixes the event exposing the old row object.
Fixes triggering the clear event in the footer slot.
Clears a lingering closing state.
Virtual-list supports horizontal scrolling with the mouse wheel on Windows and Ubuntu.
Shows the empty slot when remote search returns no results.
Prevents showOverflowTooltip from being overwritten.
Respects the column flexShrink configuration.
Keeps scrollToRow from changing the horizontal offset.
Fixes normal rendering of the default slot.
Prevents Teleport from inheriting an attribute.
Fixes incorrect scroll boundary checks.
Resolves border flicker in the checkbox dropdown.
The panel disabled state is made consistent with the component disabled state.
The date-picker input value is synchronized with the time-picker.
Fixes duplicate panels appearing after confirming time.
Removes the incorrect is-disabled class from the range panel header.
Fixes vertical misalignment of date-picker text and icons.
Fixes the dialog being unclickable when closed.
The timepicker disabled prop behavior is fixed.
The date-picker input is no longer editable when editable is false.
Removes the outline when hovering over a menu in Chrome.
Improves compatibility with new versions of sass.
Fixes the table ts-plugin(4023) error.
Avoids a resizeObserver loop when updating the tab navigation.
Optional chaining ensures el$ exists before it is accessed.
Resolves a memory leak occurring after tree data updates.
Fixes uno.css being imported multiple times.
Prevents scroll stutter when users click rapidly.
Fixes tab styling when the tab position is bottom.
Makes cascader-panel fit its width.
Fixes transparent component background colors on overlays in dark mode.
Fixes the incorrect padding value for el-upload-dragger.
Fixes a memory leak affecting focus-trap, popper, and tooltip components.
Resets the top position and label padding-right.
Fixes the button wrapping style for radio and checkbox components.
Keeps the dropdown open when the select is filterable.
Displays the mask after a panel update.
Fixes runtime validation for update:size.
Makes changes to the filterable state update reactively.
Keeps the cursor style during dragging.
The tag receives an accessibility improvement.
Handles a value of 0 correctly.
Fixes an SVG-generated mask covering the menu when scrolling.
Shows the cursor correctly when an element is disabled.
Components avoid focusing disabled elements.
Fixes input resizing not working.
Corrects the onchange parameter when the input type is file.
Fixes fallthrough of virtual-ref and virtual-triggering.
Fires the change event when an option is not checked.
Disabled options no longer receive the is-hovering state.
Skips processing keydown.enter while composing.
Fixes a ResizeObserver loop that completed with undelivered notifications.
Prevents external line-height from affecting the steps layout.
Avoids a height loop in table.
Prevents incorrect dragging when resizable is false.
Corrects the type of style.
Updates tableBody height when the header changes.
Fixes header HMR and preserves the v-if fallback.
Prevents incorrect values after the time-picker loses focus.
Corrects checkbox selection behavior when tree nodes are disabled.
Prevents scrolling beyond the virtual-list bounds.
Corrects the trigger timing of visible-change for select and select-v2.
Fixes keyboard navigation on the first of the month.
Prevents scroll wheel events outside the preview area from triggering the viewer.
Corrects the condition for resetting user input.
Fixes line breaks caused by content exceeding the available space.
Fixes a memory leak.
Prevents invalid positioning when filterable and default-first-option are used.
Fixes incorrect styling when disabled.
Allows deleting a nonexistent option.
Allows selecting options using NumpadEnter.
Does not display the input box when disabled.
Synchronizes the label when persistent is false and options change.
Fixes a memory leak after the last select unmounts.
Ensures tooltips work correctly in tree tables.
Adds the missing name attribute.
Fixes selection using the up, down, and enter keys.
Fixes checkbox selection with disabled nodes.
Prevents multiple nodes from being highlighted at the same time.
Ensures onChange receives the updated fileList.
Uses baselineOffset to render a complete canvas.
Fixes the cursor style in filterable cascader.
Adds accessibility improvements to the color picker panel's sv-panel and predefine controls.
Fixes incorrect styling when showWeekNumber is used.
Fixes value-on-clear taking effect for monthrange and yearrange.
Synchronizes the time list with input changes.
Components no longer capture focus when disabled.
Fixes cursor position after quickly clicking the icon.
Prevents pagination from overriding button styles in slots.
Uses the correct labelKey in selectedLabel.
Prevents 'false' from displaying incorrectly during remote search.
Fixes select affecting global configuration.
Prevents duplicate option registration.
Ensures scrolling is triggered when an option value is zero.
Makes content hover work with an array trigger.
Fixes expand and collapse icon status when calling collapseNode or expandNode.
Improves tree-select empty detection.
Fixes lock-scroll not working.
Fixes a memory leak in the directive.
Fixes levels expanding during search.
Fixes the panel not capturing focus.
Fixes an incorrect displayed value when persistent is false.
Fixes button offset when using unocss.
Fixes dynamically toggling a form item slot.
The color-picker-panel hue slider receives an accessibility improvement.
Fixes arrow-key repeating and disabled-scientific behavior.
Fixes precision with step-strictly.
Fixes failure to capture focus.
Fixes the label not showing when persistent is false.
Fixes loading appearing on the first click when remote is enabled.
Cancel now consistently takes the old value.
Closes the tooltip when an iframe is clicked.
Corrects the drop indicator when the tree has a scroll offset.
Fixes an invalid CSS variable.