UI Package Reference (resuxjs/ui)

resuxjs/ui is an optional Vue UI and motion package. This page documents the package-level public API. Every component has a dedicated page in the UI component catalog.

Runtime boundary

All Rx* / Resux* components in this package are Vue defineComponent components. Use them inside a Vue island or another explicit Vue runtime boundary. They are not zero-hydration Resux template primitives.

Import surface

import uiModule, {
  defineUiTokens,
  isReducedMotion,
  useAnimate,
  vAnime,
  vAnimate,
  RxButton,
  ResuxButton
} from 'resuxjs/ui'

Module options

export interface ResuxUiModuleOptions {
  css?: string[]
  tokens?: Record<string, unknown>
  defaultStyles?: boolean
  animations?: {
    enabled?: boolean
    defaultPreset?: string
  }
}

Option	Default	Behavior
css	[]	Calls the module CSS registration hook for each configured path.
tokens	{}	Stored in public runtime UI configuration. Arbitrary token keys/values are not automatically converted into built-in component CSS variables.
defaultStyles	true	Injects the built-in rx-* primitive stylesheet when enabled.
animations.enabled	true	Controls injection of the package's animation CSS definitions.
animations.defaultPreset	'fade-up'	Exposed as runtime animation configuration.

Example:

export default defineResuxConfig({
  modules: [
    ['resuxjs/ui', {
      css: ['/assets/css/ui-overrides.css'],
      defaultStyles: true,
      tokens: {
        accent: '#03c8bf'
      },
      animations: {
        enabled: true,
        defaultPreset: 'fade-up'
      }
    }]
  ]
})

defineUiTokens(tokens)

Typed identity helper for token records:

export function defineUiTokens<T extends Record<string, unknown>>(
  tokens: T
): T

const tokens = defineUiTokens({
  accent: '#03c8bf',
  spacingScale: [4, 8, 12, 16]
})

The helper returns the same object and preserves its inferred record type. It does not generate CSS by itself.

AnimationPreset

type AnimationPreset =
  | 'fade-up'
  | 'fade-down'
  | 'scale-in'
  | 'slide-in-left'
  | 'slide-in-right'
  | 'pulse-glow'
  | 'bounce-in'

These names have verified keyframes in useAnimate().

AnimateOptions

export interface AnimateOptions {
  type?: AnimationPreset | string
  duration?: number
  delay?: number
  easing?: string
  fill?: FillMode
}

Defaults used by useAnimate():

• type: 'fade-up'
• duration: 400
• delay: 0
• easing: 'cubic-bezier(0.16, 1, 0.3, 1)'
• fill: 'forwards'

The type accepts custom strings for compatibility. A string that is not one of the verified presets falls through to the helper's default fade/translate keyframes rather than creating a new named preset automatically.

isReducedMotion()

export function isReducedMotion(): boolean

Returns false outside a browser. In a browser it checks:

(prefers-reduced-motion: reduce)

Use this for browser-owned motion that should respect the user's reduced-motion preference.

useAnimate(target, options)

export function useAnimate(
  target:
    | HTMLElement
    | { value: HTMLElement | null }
    | null,
  options?: AnimateOptions
): Animation | null

The helper accepts either a direct HTML element or a ref-like object whose value is an HTML element. Direct form elements are treated as elements even though they also expose their own .value property.

The helper returns null when:

• there is no browser window;
• target resolves to null;
• reduced motion is requested;
• the resolved target does not expose Element.animate.

Otherwise it invokes the Web Animations API and returns the resulting Animation.

const animation = useAnimate(element, {
  type: 'fade-up',
  duration: 500,
  delay: 100,
  easing: 'ease-out',
  fill: 'forwards'
})

The caller owns cancellation/lifecycle when using the imperative helper directly.

vAnime / vAnimate

vAnimate is an alias of vAnime.

The Vue directive:

• reads either a preset string or options object;
• uses IntersectionObserver when available;
• starts animation as the element approaches/enters the viewport;
• defaults its own fill behavior to 'both' unless explicitly configured;
• disconnects its observer after activation;
• cancels an active animation and disconnects the observer during unmount cleanup;
• falls back to immediate animation when IntersectionObserver is unavailable.

Example in Vue-owned markup:

<div v-anime="{ type: 'fade-up', duration: 500 }">
  Content
</div>

The directive is a Vue directive; do not present it as a native Resux template directive.

Public components

Every Rx* component has an equivalent Resux* alias.

Component	Dedicated reference
RxButton / ResuxButton	Button
RxInput / ResuxInput	Input
RxTextarea / ResuxTextarea	Textarea
RxSelect / ResuxSelect	Select
RxDatePicker / ResuxDatePicker	DatePicker
RxSwitch / ResuxSwitch	Switch
RxCard / ResuxCard	Card
RxBadge / ResuxBadge	Badge
RxAvatar / ResuxAvatar	Avatar
RxAlert / ResuxAlert	Alert
RxSkeleton / ResuxSkeleton	Skeleton
RxDivider / ResuxDivider	Divider
RxKbd / ResuxKbd	Kbd
RxAccordion / ResuxAccordion	Accordion
RxTabs / ResuxTabs	Tabs
RxPopover / ResuxPopover	Popover
RxDropdown / ResuxDropdown	Dropdown
RxTooltip / ResuxTooltip	Tooltip
RxModal / ResuxModal	Modal
RxMotion / ResuxMotion	Motion
RxReveal / ResuxReveal	Reveal
RxAutoAnimate / ResuxAutoAnimate	AutoAnimate
RxIcon / ResuxIcon	UI Icon primitive

Important implementation boundaries

RxReveal

It runs a mount-time animation. It does not use viewport observation. For IntersectionObserver-triggered Vue animation, use vAnime / vAnimate.

RxAutoAnimate

It runs a one-time scale-in animation after mount. It does not observe child insertion/removal/reordering or layout changes.

UI RxIcon

It renders text like [check]; it is not the SVG registry/provider component. For SVG icons use resuxjs/icons.

Styling and unstyled

Most UI components expose unstyled. When true, component-specific Resux classes are omitted while user attributes/classes still pass through according to Vue attribute inheritance.

The default stylesheet is intentionally simple. Do not infer undeclared design-token behavior from the presence of tokens configuration.

Accessibility

Native-element primitives inherit useful browser semantics. Several custom widgets are intentionally small and currently lack parts of complete ARIA interaction patterns. The dedicated component pages identify those limitations explicitly.

Do not claim full keyboard/focus/screen-reader behavior without source/tests demonstrating it.

SSR / hydration cost

Component markup may be rendered through Vue SSR, but interaction/state/mount hooks require the Vue runtime boundary. The cost is the island/subtree, not an imaginary Resux zero-JS component contract.

For built-in resumable media, see Images and Media.

Related

• Component catalog
• UI and Motion guide
• Vue Islands
• Current Limits