Skip to content

Design conventions ​

Project scope ​

Fast.Element.Plus is the open-source SDK for Fast business components. Team efficiency and consistent interaction take priority, including intentional changes to Element Plus defaults, events, and workflows.

Native capabilities ​

Wrappers forward Element Plus props, events, slots, and expose where appropriate, but are not transparent proxies. Fast additions, overrides, and unsupported features follow these docs and public TypeScript types.

Every Element Plus minor upgrade, such as 2.14.x to 2.15.x or later, requires reviewing props, emits, slots, expose, defaults, and internal styles. See the compatibility checklist.

Asynchronous business flows ​

FaDialog and FaDrawer open/close events indicate completion of Fast business hooks:

  • open fires after afterOpen completes.
  • close fires after closeFunction or beforeClose completes.
  • Components remain loading while waiting to prevent repeated actions.

This intentionally differs from the DOM timing of same-named native Element Plus lifecycle events.

Selector models and events ​

FaSelect, FaSelectPage, FaSelectV2, FaTreeSelect, and FaInputDialogPage separate model updates from business-data events:

  • update:modelValue is the sole selected-value update channel and preserves native value types; clearing multiple selection still produces an array.
  • FaSelect, FaSelectPage, FaSelectV2, and FaTreeSelect retain change(data, value): an option object for single selection, option objects for multiple selection, and null on clear. It does not update the model again.
  • Other events such as clear, remove-tag, and check preserve Element Plus arguments.
  • v-model:label is derived from current values and options; applications may instead handle labels through update:modelValue.
  • FaTreeSelect node-click only means a node was clicked. Determine final selection through update:modelValue, change, or check.
  • FaInputDialogPage change(data, value) returns confirmed rows and values. selectionRow expose tracks selected rows and clears with the selection.

Programmatic selection through expose updates the model without synthesizing native user-change events.

FaTree emits change(data, node, instance, event) only when the current value changes; node-click always represents a click.

Upload models and callbacks ​

  • FaUpload, FaUploadImage, and FaUploadImages emit uploaded URL models only through update:modelValue.
  • onChange(uploadFile, uploadFiles) remains an Element Plus file-state callback, without URL strings or arrays mixed in.
  • Clearing multiple files emits []; clearing a single file emits null.
  • update:fileList writes only when the list changes, without duplicate assignment during removal callbacks.

Styles and themes ​

  • Colors, borders, backgrounds, and text prefer --el-* variables, following application theme changes.
  • Component-specific variables such as --fa-dialog-* and --fa-table-* remain only where they express component semantics.
  • Shared SCSS breakpoints cover phone, tablet, and desktop layouts.
  • Existing public variables such as --width remain supported.
  • Size styles follow the dynamic size from ElConfigProvider. Each component root declares its own default size variables so nested components do not inherit an outer compact size.
  • Runtime size classes use ${baseClass}-${size}, such as fa-dialog-small and fa-form-detail-small. SCSS keeps component element class names explicit, uses shallow nesting for related children, and uses & for same-element states, pseudo-classes and pseudo-elements.
  • Prefer component props, Element Plus theme variables and explicitly documented CSS variables when customizing styles; for example, use --fa-table-expand-width for expansion width. Internal DOM paths and internal positioning classes are not stable customization APIs.
  • Teleported poppers use their own fa-* namespaces and size classes rather than relying on the original component DOM ancestors.

The 2.0.25 source uses shallow nesting and selective context specificity reduction. Reduced-motion mode disables the custom Loading animation and size transitions on tables, dialogs and drawers. Desktop drawer resize handles now have an 8px hit area inside the body; mobile handles remain hidden. Detail forms now generate fa-form-detail-default, fa-form-detail-small and fa-form-detail-large. Legacy underscore size classes and compatibility selectors have been removed; migrate any custom overrides accordingly. The documentation demos and automatic API tables use 2.0.27.

Public API ​

Props, Emits, Slots, Expose, instances, and helper types are public APIs. The current release does not promise stable compatibility; breaking changes must update types, examples, API documentation, and Changelog together.