Vue Horizontal Layout Component

Common errors

• [Vue warn]: Failed to resolve component: vue-horizontal

  cause The `VueHorizontal` component was not properly registered with Vue, either globally or locally within the component where it's being used.
  fix Ensure `import VueHorizontal from 'vue-horizontal';` is present and the component is added to `components: { VueHorizontal }` in your Vue component or globally via `Vue.component('VueHorizontal', VueHorizontal);`.

• TypeError: Cannot read properties of null (reading '$refs')

  cause This error often occurs in SSR environments or when attempting to access a `$ref` before the component has been mounted and the DOM element is available.
  fix Guard `$refs` access with `if (this.$refs.container)` or defer DOM-dependent logic to `mounted()` lifecycle hook or `this.$nextTick()` callback.

• SyntaxError: Unexpected token 'export' (for require('vue-horizontal'))

  cause Attempting to import the ESM-only `vue-horizontal` package using CommonJS `require()` syntax in an environment that expects ESM modules.
  fix Use ESM `import` statements: `import VueHorizontal from 'vue-horizontal';`. Ensure your build setup (Webpack, Rollup, Vite) is configured to handle ESM correctly.

Warnings

• breaking Vue 3 compatibility requires installing the `@next` version of the package. The main `vue-horizontal` package currently targets Vue 2.
  Fix: For Vue 3 projects, use `npm install vue-horizontal@next` or `yarn add vue-horizontal@next`.
• gotcha When using Server-Side Rendering (SSR), ensure that DOM-dependent operations (like accessing `$refs.container` children) are properly guarded or performed only client-side to prevent errors during the server build process.
  Fix: Check for the presence of `$refs` or use `this.$nextTick` for DOM manipulations. Ensure your SSR environment correctly handles component lifecycle.
• gotcha Careful consideration of CSS styling is required, especially for the last child element within the horizontal layout. Previous versions had specific fixes related to margins on the last child that could cause layout inconsistencies.
  Fix: Ensure your custom CSS does not override critical layout properties applied by the component. Refer to the documentation's design principles for best practices.
• gotcha The `refresh` callback was previously mandatory but has been made optional. If you're using an older version or encountering issues with `refresh`, ensure your implementation aligns with the expected API.
  Fix: Update to the latest `0.8.x` version to ensure `refresh` callback optionality. Check documentation for the current `refresh` signature if manually calling it.

Install

• npm install vue-horizontal npm
• yarn add vue-horizontal yarn
• pnpm add vue-horizontal pnpm

Imports

• VueHorizontal
  wrong:

  const VueHorizontal = require('vue-horizontal');

  correct:

  import VueHorizontal from "vue-horizontal";

  CommonJS `require` is not supported; use ESM imports. Vue 3 users should install `vue-horizontal@next`.
• VueHorizontal (Global)
  wrong:

  import Vue from 'vue';
  import VueHorizontal from 'vue-horizontal';
  
  Vue.component(VueHorizontal);

  correct:

  import Vue from 'vue';
  import VueHorizontal from 'vue-horizontal';
  
  Vue.component('VueHorizontal', VueHorizontal);

  When registering globally, ensure you provide a string name for the component.
• Type (Props)

  import type { VueHorizontalProps } from 'vue-horizontal';

  The package ships with TypeScript types. The primary component props are typically exposed via an interface like `VueHorizontalProps` or similar.

Quickstart

Demonstrates importing and using VueHorizontal with a v-for loop to render a dynamic list of items.

<template>
  <vue-horizontal responsive>
    <section v-for="item in items" :key="item.title">
      <h3>{{ item.title }}</h3>
      <p>{{ item.content }}</p>
    </section>
  </vue-horizontal>
</template>

<script>
import VueHorizontal from "vue-horizontal";

export default {
  components: {VueHorizontal},
  data() {
    return {
      items: [...Array(20).keys()].map((i) => {
        return {title: `Item ${i}`, content: `🚀 Content ${i}`};
      }),
    }
  }
}
</script>

<style scoped>
section {
  padding: 16px 24px;
  background: #f5f5f5;
}
</style>