reka-ui-skilld（雷卡 ui 熟练）

unovue/reka-ui reka-ui@2.9.6

Tags: latest: 2.9.6

References: Docs

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

• BREAKING: radix-vue renamed to reka-ui — CSS variables now use --reka- prefix and data attributes use data-reka- source
• BREAKING: Combobox refactor — filter-function prop removed; searchTerm and displayValue props moved from Root to ComboboxInput source
• BREAKING: Checkbox, Toggle, MenuCheckboxItem — bindings changed from v-model:checked or v-model:pressed to standard v-model source
• BREAKING: DatePicker/Calendar — weekStartsOn is now locale-independent as of v2.8.0 source
• BREAKING: Presence — forceMount now renders components regardless of active state; manual visibility handling (e.g. :hidden) is required source
• BREAKING: Pagination — itemsPerPage prop is now required rather than having a default value source
• NEW: Rating component — added for star/rating input interactions in v2.8.0 source
• NEW: TimeField component — new primitive for localized time inputs introduced in v2.0.0 source
• NEW: useFilter() — locale-aware string filtering utility (startsWith, endsWith, contains) added in v2.0.0 source
• NEW: useLocale() / useDirection() — utility hooks for accessing the current configuration context source
• NEW: ScrollArea glimpse mode — added ScrollAreaScrollbarGlimpse for transient scrollbar visibility source
• NEW: Select disableOutsidePointerEvents — prop added to SelectContent to control interaction with outside elements source
• NEW: ConfigProvider — global configuration component for locale, direction, and useId settings source
• NEW: NumberField enhancements — added focusOnChange, readonly, and stepSnapping props source

Also changed: Popover/Dialog programmatic close · Combobox openOnFocus props · Slider thumbAlignment prop · Toast disableSwipe prop · ContextMenu pressOpenDelay prop · Presence component exposed · calendar getWeekNumber utility · injectContext exposed · Collapsible/Accordion unmountOnHide prop

Best Practices

• Use the asChild prop to compose Reka's functionality onto your own Vue components or alternative DOM elements while maintaining accessibility source

<TooltipTrigger asChild>
  <MyButton>Hover me</MyButton>
</TooltipTrigger>

• Utilize useForwardPropsEmits when building wrapper components to automatically forward all props and emits to the underlying Reka primitive source

const props = defineProps<AccordionRootProps>()
const emits = defineEmits<AccordionRootEmits>()
const forwarded = useForwardPropsEmits(props, emits)
// Usage: <AccordionRoot v-bind="forwarded">

• Wrap your application with ConfigProvider to manage global reading direction (RTL) and prevent layout shifts during scroll locking source

<ConfigProvider dir="rtl" :scroll-body="false">
  <App />
</ConfigProvider>

• Apply useForwardExpose in components with multiple root nodes (fragments) to ensure that template refs correctly return the target DOM element source

const { forwardRef } = useForwardExpose()
// Usage: <div :ref="forwardRef">...</div>

• Implement ComboboxVirtualizer or ListboxVirtualizer for large datasets to improve performance, ensuring the parent container has a fixed height source

<ComboboxViewport class="max-h-80 overflow-y-auto">
  <ComboboxVirtualizer :options="items" :estimate-size="25" v-slot="{ option }">
    <ComboboxItem :value="option">{{ option.label }}</ComboboxItem>
  </ComboboxVirtualizer>
</ComboboxViewport>

• Use injectXContext functions (e.g., injectAccordionRootContext) to access internal primitive state for advanced custom child components source
• Style component states by targeting data-state attributes (e.g., open, closed, active) instead of manually toggling classes source

/* Preferred way to style open state */
.AccordionItem[data-state="open"] {
  border-bottom-width: 2px;
}

• Use the :deep() selector when styling teleported components (Dialog, Popover, Tooltip) within scoped Vue styles to reach the body-appended elements source
• Enable force-mount on content parts when using JavaScript animation libraries or Vue <Transition> to delegate unmounting control to the library source

<Transition name="fade">
  <DialogContent force-mount>...</DialogContent>
</Transition>

• Prefer Vue 3.5 native useId() over the Reka UI utility for stable SSR identifiers, as the library utility is deprecated for newer Vue versions source