Reka UI - Vue Headless Components

Common errors

• TS2307: Cannot find module 'reka-ui' or its corresponding type declarations.

  cause TypeScript compiler cannot locate the type definitions for reka-ui, or the package itself is not installed.
  fix Ensure 'reka-ui' is installed (`npm install reka-ui`) and your `tsconfig.json` includes `"compilerOptions": { "allowSyntheticDefaultImports": true }` if you're mixing CJS/ESM, though `reka-ui` primarily uses named exports.

• Vue warn: Failed to resolve component: RekaButton (or similar component name). If this is a native custom element, ensure it's registered with Vue's compilerOptions.

  cause The Reka UI component was not correctly imported or registered within the Vue component where it's being used.
  fix Verify that you have correctly imported the component using named imports (e.g., `import { RekaButton } from 'reka-ui'`) and that the component name in your template exactly matches the imported name (e.g., `<RekaButton>`).

• Property 'weekStartsOn' does not exist on type '...' for DatePicker/Calendar components.

  cause You are using a `weekStartsOn` prop that was changed in Reka UI v2.8.0. The previous type signature or interpretation might be causing a mismatch.
  fix If you recently updated to Reka UI v2.8.0+, review your usage of `weekStartsOn` to conform to its new locale-independent behavior. Ensure the value provided matches the expected type and range (e.g., 0 for Sunday, 1 for Monday).

• Error: Cannot find module 'vue' or 'vue/dist/vue.runtime.esm-bundler.js'

  cause Your project's `vue` dependency might be missing or an incompatible version with `reka-ui`.
  fix Ensure `vue` is installed and meets the `reka-ui` peer dependency requirement (Vue >= 3.4.0). Run `npm install vue@latest` or `pnpm update vue`.

Warnings

• breaking The `weekStartsOn` prop for DatePicker, DateRangePicker, Calendar, and RangeCalendar components was made locale-independent. If you were relying on its previous behavior that might have been tied to specific locale settings, you will need to adjust your implementation.
  Fix: Review and update the `weekStartsOn` prop usage in affected date components to ensure it aligns with the new locale-independent behavior. You might need to explicitly set the desired start day of the week.
• gotcha Reka UI components are 'headless' or 'unstyled'. This means they provide functionality and accessibility features, but no visual styling by default. Developers are responsible for providing all styling (CSS, Tailwind, etc.) for the components.
  Fix: Ensure you apply custom CSS classes or inline styles to Reka UI components to achieve the desired visual appearance. Refer to the Reka UI documentation for component structure to target elements correctly.
• gotcha Reka UI has a peer dependency on Vue >= 3.4.0. Using it with older versions of Vue 3 might lead to unexpected behavior, warnings, or runtime errors.
  Fix: Upgrade your project's Vue dependency to version 3.4.0 or newer: `npm install vue@latest` or `pnpm update vue`.
• gotcha Many Reka UI components are composed of multiple sub-components (e.g., `RekaDialogRoot`, `RekaDialogTrigger`, `RekaDialogContent`). Incorrectly importing or structuring these sub-components can lead to non-functional or inaccessible UI.
  Fix: Always consult the Reka UI documentation for the specific component you are using to understand its required structure and the correct sub-components to import and use together.

Install

• npm install reka-ui npm
• yarn add reka-ui yarn
• pnpm add reka-ui pnpm

Imports

• RekaButton
  wrong:

  import RekaButton from 'reka-ui'

  correct:

  import { RekaButton } from 'reka-ui'

  Reka UI components are typically named exports, not default exports. Named with 'Reka' prefix to avoid conflicts.
• RekaDialogRoot
  wrong:

  import { DialogRoot } from 'reka-ui'

  correct:

  import { RekaDialogRoot, RekaDialogTrigger, RekaDialogContent } from 'reka-ui'

  Many complex components are composed of multiple named exports. Ensure all necessary parts are imported, usually with the 'Reka' prefix.
• TimeRange

  import type { TimeRange } from 'reka-ui'

  Specific types are exported for use with TypeScript. The 'type' keyword is recommended for type-only imports.

Quickstart

Demonstrates the basic usage of a Reka Dialog component, including opening, content, and closing. It highlights the headless nature by showing required custom styling.

<!-- src/components/MyDialog.vue -->
<script setup lang="ts">
import { ref } from 'vue';
import { RekaButton, RekaDialogRoot, RekaDialogTrigger, RekaDialogContent, RekaDialogTitle, RekaDialogDescription } from 'reka-ui';

const isDialogOpen = ref(false);
</script>

<template>
  <RekaDialogRoot v-model:open="isDialogOpen">
    <RekaDialogTrigger as-child>
      <RekaButton class="my-custom-button">Open Dialog</RekaButton>
    </RekaDialogTrigger>
    <Teleport to="body">
      <RekaDialogContent class="my-dialog-content">
        <RekaDialogTitle class="my-dialog-title">My Dialog Title</RekaDialogTitle>
        <RekaDialogDescription class="my-dialog-description">
          This is an accessible dialog, built with Reka UI primitives.
          You need to provide your own styling for these headless components.
        </RekaDialogDescription>
        <RekaButton @click="isDialogOpen = false" class="my-close-button">Close</RekaButton>
      </RekaDialogContent>
    </Teleport>
  </RekaDialogRoot>
</template>

<style scoped>
.my-custom-button {
  padding: 10px 20px;
  background-color: #4CAF50;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.my-dialog-content {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  background-color: white;
  padding: 20px;
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  z-index: 1000;
  min-width: 300px;
}

.my-dialog-title {
  font-size: 1.5em;
  margin-bottom: 10px;
}

.my-dialog-description {
  margin-bottom: 15px;
}

.my-close-button {
  background-color: #f44336;
  color: white;
  padding: 8px 15px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  float: right;
}
</style>