Vue Flickity Component

Common errors

• [Vue warn]: Failed to mount component: template or render function not defined. (found in <Root>)

  cause Attempting to use `vue-flickity` in a Vue 3 application.
  fix This component is for Vue 2 only. Downgrade Vue to 2.x or switch to a Vue 3 compatible carousel library.

• TypeError: Cannot read properties of undefined (reading 'next')

  cause This typically occurs when `$refs.flickity` is undefined, meaning the component hasn't mounted yet, or the ref name is incorrect, or the component itself failed to initialize.
  fix Ensure the `flickity` component has a `ref="flickity"` attribute and that you are calling methods only after the component has been mounted (e.g., in `mounted()` lifecycle hook or within a `v-if` check).

• Carousel cells appear as a static list, not a sliding carousel.

  cause Flickity's essential CSS (`flickity.css`) has not been imported or included in the project, preventing the library from styling and activating the carousel.
  fix Import `flickity/css/flickity.css` in your project's main JavaScript file (e.g., `main.js`) or include it via a `<link>` tag in your HTML.

Warnings

• breaking The `vue-flickity` package is abandoned and has not been updated in over seven years. It is not maintained and may contain security vulnerabilities or compatibility issues with newer environments.
  Fix: For new projects, consider modern, actively maintained carousel libraries for Vue 3+. For existing Vue 2 projects, proceed with caution and thorough testing.
• breaking This package exclusively supports Vue 2.x and is incompatible with Vue 3 or later versions. Attempting to use it in a Vue 3 project will result in runtime errors related to component registration or template compilation.
  Fix: Ensure your project is running Vue 2.x. If migrating to Vue 3, you must replace `vue-flickity` with a Vue 3-compatible carousel solution.
• gotcha The `vue-flickity` component does not bundle Flickity.js's CSS. Users must manually import the Flickity CSS (e.g., `import 'flickity/css/flickity.css';`) in their project's entry point or main CSS file for the carousel to render correctly.
  Fix: Add `import 'flickity/css/flickity.css';` to your main JavaScript file or link the CSS directly in your HTML.
• gotcha If content inside the carousel cells changes dynamically after the component mounts, Flickity might not re-calculate cell positions correctly. This can lead to misaligned or non-functional carousels.
  Fix: After dynamic content updates, manually call `this.$refs.flickity.flickity.reloadCells()` or `this.$refs.flickity.flickity.resize()` to force Flickity to re-evaluate the layout.

Install

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

Imports

• Flickity
  wrong:

  const Flickity = require('vue-flickity');

  correct:

  import Flickity from 'vue-flickity';

  The primary component is exported as a default import.

Quickstart

This quickstart demonstrates how to integrate `vue-flickity` into a Vue 2 application, configure it with various options, and implement custom navigation using component methods.

import Vue from 'vue';
import Flickity from 'vue-flickity';

// You would typically import Flickity's CSS in your main entry file
// import 'flickity/css/flickity.css'; 

new Vue({
  el: '#app',
  components: {
    Flickity
  },
  
  data() {
    return {
      flickityOptions: {
        initialIndex: 1,
        prevNextButtons: true,
        pageDots: true,
        wrapAround: true,
        cellAlign: 'left'
        // any options from Flickity can be used
      }
    }
  },
  
  methods: {
    next() {
      if (this.$refs.flickity) {
        this.$refs.flickity.next();
      }
    },
    
    previous() {
      if (this.$refs.flickity) {
        this.$refs.flickity.previous();
      }
    }
  },
  template: `
    <div id="app">
      <h1>My Flickity Carousel</h1>
      <flickity ref="flickity" :options="flickityOptions">
        <div class="carousel-cell" style="width: 80%; height: 200px; background-color: #f0f0f0; margin-right: 10px; display: flex; align-items: center; justify-content: center;">Cell 1</div>
        <div class="carousel-cell" style="width: 80%; height: 200px; background-color: #e0e0e0; margin-right: 10px; display: flex; align-items: center; justify-content: center;">Cell 2</div>
        <div class="carousel-cell" style="width: 80%; height: 200px; background-color: #d0d0d0; margin-right: 10px; display: flex; align-items: center; justify-content: center;">Cell 3</div>
        <div class="carousel-cell" style="width: 80%; height: 200px; background-color: #c0c0c0; margin-right: 10px; display: flex; align-items: center; justify-content: center;">Cell 4</div>
        <div class="carousel-cell" style="width: 80%; height: 200px; background-color: #b0b0b0; margin-right: 10px; display: flex; align-items: center; justify-content: center;">Cell 5</div>
      </flickity>

      <!-- Example custom navigation buttons -->
      <button @click="previous()">Custom Previous Button</button>
      <button @click="next()">Custom Next Button</button>
    </div>
  `
});