Vuesax v3

Common errors

• TypeError: Cannot read property 'filter' of undefined

  cause Often occurs in Vuesax components (e.g., Table component) when data properties expected to be arrays are undefined or null, leading to runtime errors during rendering.
  fix Ensure that data bound to Vuesax components that expect arrays (like `vs-table`'s `data` prop) is always initialized as an array (e.g., `[]`) to prevent `undefined` access.

• RangeError: Maximum call stack size exceeded

  cause Can happen with complex component nesting or improper lifecycle hook usage within Vuesax components, leading to infinite recursion.
  fix Review component nesting, especially with components like `vs-dropdown` or `vs-select`, and ensure no reactive property updates trigger endless re-renders. Check for circular dependencies or incorrect `beforeDestroy` hook implementations.

• Notification and dialog component gives console error

  cause Generic console errors often indicate issues with component state, improper prop usage, or conflicts with global styles/scripts affecting Vuesax's internal logic.
  fix Check the specific console error message for more details. Ensure all required props are passed correctly and that there are no conflicting global styles or JavaScript interfering with Vuesax's internal DOM manipulation for notifications and dialogs.

Warnings

• breaking The `vuesax` package (v3) is designed for Vue 2. Attempting to use it directly in a Vue 3 project will lead to incompatibility issues and errors, as Vue 3 introduced significant breaking changes to its API.
  Fix: For Vue 3 compatibility, use the community-maintained `vuesax3` package (npm: `vuesax3`) or migrate to the officially supported Vuesax v4 (`vuesax-next`), which is a complete rewrite.
• gotcha The original `vuesax` npm package (v3.x.x) is largely unmaintained by its original author, with its last publish date being several years ago for version 3.12.2. Critical bug fixes or new features are unlikely to be released for this version.
  Fix: For active development and support, especially with Vue 3, consider using `vuesax3` or the Vuesax v4 (`vuesax-next`) project. If you must use v3, be aware that you are on an unmaintained branch.
• gotcha Vuesax v3 requires an explicit CSS import (`import 'vuesax/dist/vuesax.css'`) for its components to render with the correct styling. Forgetting this import will result in unstyled (plain HTML-looking) components.
  Fix: Ensure `import 'vuesax/dist/vuesax.css';` is included once in your main application entry point (e.g., `main.js` or `App.vue`'s script section if using a build tool).
• breaking Vuesax v4 (`vuesax-next`) is a complete rewrite with different underlying technologies (e.g., TypeScript, Sass instead of Stylus) and significantly altered APIs compared to Vuesax v3. Migration from v3 to v4 is not a direct upgrade but requires substantial refactoring.
  Fix: Consult the Vuesax v4 documentation for migration guides and new API specifications if you plan to upgrade from a Vue 2 Vuesax v3 project to a Vue 3 Vuesax v4 project. It's often easier to start a new project with V4.

Install

• npm install vuesax npm
• yarn add vuesax yarn
• pnpm add vuesax pnpm

Imports

• Vuesax (full bundle)
  wrong:

  const Vuesax = require('vuesax'); // CommonJS import for ESM-first projects
  Vue.use(Vuesax);

  correct:

  import Vuesax from 'vuesax';
  Vue.use(Vuesax);

  This imports the entire Vuesax library, including all components and styles. Recommended for smaller projects or if you use most components. For Vue 2 applications.
• Individual components
  wrong:

  import { Button, Select } from 'vuesax'; // Incorrect component naming convention
  import vsButton from 'vuesax/lib/vsButton';

  correct:

  import { vsButton, vsSelect } from 'vuesax';
  Vue.use(vsButton);
  Vue.use(vsSelect);

  Allows for tree-shaking and smaller bundle sizes by only importing the necessary components. Component names are prefixed with 'vs'.
• Global CSS
  wrong:

  import 'vuesax/dist/style.css'; // Incorrect path
  // No CSS import at all

  correct:

  import 'vuesax/dist/vuesax.css';

  This import is mandatory for Vuesax components to be styled correctly. It should be included once in your main application entry file.

Quickstart

Demonstrates how to set up Vuesax v3 in a Vue 2 project, registering individual components and importing the necessary global CSS.

import Vue from 'vue';
import App from './App.vue';
import { vsButton, vsInput } from 'vuesax';
import 'vuesax/dist/vuesax.css'; // Don't forget the styles!

Vue.use(vsButton);
Vue.use(vsInput);

new Vue({
  render: h => h(App),
}).$mount('#app');

// App.vue example (inside <template>):
// <template>
//   <div id="app">
//     <vs-button type="primary">Hello Vuesax</vs-button>
//     <vs-input placeholder="Enter text" v-model="myValue"/>
//   </div>
// </template>
//
// (inside <script>):
// export default {
//   name: 'App',
//   data() {
//     return {
//       myValue: ''
//     }
//   }
// }