Vue Component Integration

Pagiflow Vue
Documentation

Official Vue integration docs for Pagiflow. Learn component props, Composition API (usePagiflow), imperative methods, and full feature integration for Vue 3.

30+ Options
12+Methods
0Dependencies
∞Possibilities

Vue Integration

Install and use Pagiflow in Vue with pagiflow/vue. Use the <Pagiflow> component for standard Vue usage; use usePagiflow when binding to a raw DOM element.

Install
npm i pagiflow
Usage
<script setup>
import { Pagiflow, PagiflowSlide } from 'pagiflow/vue';
import 'pagiflow/css';
</script>

<template>
  <Pagiflow :options="{ nav: true, loop: true, itemsPerSlide: 1 }">
    <PagiflowSlide><div>Slide 1</div></PagiflowSlide>
    <PagiflowSlide><div>Slide 2</div></PagiflowSlide>
    <PagiflowSlide><div>Slide 3</div></PagiflowSlide>
  </Pagiflow>
</template>
Composition API

For more control, use the usePagiflow hook to initialize the slider on a raw HTMLElement ref. Do not pass a component ref here.

<script setup>
import { usePagiflow } from 'pagiflow/vue';
import 'pagiflow/css';

const { sliderRef, next, prev } = usePagiflow({
  loop: true,
  itemsPerSlide: 3
});
</script>

<template>
  <div class="controls">
    <button @click="prev">Prev</button>
    <button @click="next">Next</button>
  </div>

  <div ref="sliderRef" class="my-slider">
    <div>Slide 1</div>
    <div>Slide 2</div>
    <div>Slide 3</div>
  </div>
</template>
Options
<script setup>
const sliderOptions = {
  nav: true,
  loop: true,
  itemsPerSlide: 3,
  autoplay: true,
  autoplayDelay: 2500
};
</script>

<template>
  <Pagiflow :options="sliderOptions">
    <!-- slides -->
  </Pagiflow>
</template>
Methods
<script setup lang="ts">
import { ref } from 'vue';
import { Pagiflow, type PagiflowInstance } from 'pagiflow/vue';

const slider = ref<{
  instance: PagiflowInstance | null;
  currentIndex: number;
  next: () => void;
  prev: () => void;
  goTo: (index: number, opts?: { silent?: boolean; instant?: boolean }) => void;
  togglePlayPause: () => void;
} | null>(null);

const handleNext = () => slider.value?.next();
const handlePrev = () => slider.value?.prev();
const goToThird = () => slider.value?.goTo(2);
const pauseOrPlay = () => slider.value?.togglePlayPause();
</script>

<template>
  <button @click="handlePrev">Prev</button>
  <button @click="handleNext">Next</button>
  <button @click="goToThird">Go to 3rd</button>
  <button @click="pauseOrPlay">Play/Pause</button>

  <Pagiflow ref="slider" :options="{ itemsPerSlide: 1 }">
    <!-- slides -->
  </Pagiflow>
</template>

Thumbnail Navigation

Show thumbnail strip that syncs with the main slider. Supports top, bottom, left, and right positions.

Thumbnails bottom
<template>
  <Pagiflow
    :options="{
      loop: true,
      thumbnails: {
        enabled: true,
        position: 'bottom',
        thumbWidth: 90,
        gap: 6
      }
    }"
  >
    <PagiflowSlide><img src="/img/1.jpg" alt="1" /></PagiflowSlide>
    <PagiflowSlide><img src="/img/2.jpg" alt="2" /></PagiflowSlide>
    <PagiflowSlide><img src="/img/3.jpg" alt="3" /></PagiflowSlide>
  </Pagiflow>
</template>

Slider Sync

Connect two slider instances together for synchronized navigation.

How it works: Use CSS selectors to link sliders. When one moves, the other follows.
Synchronized Sliders
<template>
  <!-- Main Slider -->
  <Pagiflow id="main-slider" :options="{ loop: true }">
    <PagiflowSlide>Main 1</PagiflowSlide>
    <PagiflowSlide>Main 2</PagiflowSlide>
    <PagiflowSlide>Main 3</PagiflowSlide>
  </Pagiflow>

  <!-- Nav Slider -->
  <Pagiflow 
    :options="{ 
      itemsPerSlide: 3, 
      sync: '#main-slider',
      loop: true 
    }"
  >
    <PagiflowSlide>Thumb 1</PagiflowSlide>
    <PagiflowSlide>Thumb 2</PagiflowSlide>
    <PagiflowSlide>Thumb 3</PagiflowSlide>
  </Pagiflow>
</template>

Responsive Breakpoints

Customize slider behavior across different screen sizes.

Adaptive Responsive Layout
<template>
  <Pagiflow
    :options="{
      nav: true,
      responsive: {
        0: { itemsPerSlide: 1, gap: 0 },
        768: { itemsPerSlide: 2, gap: 16 },
        1200: { itemsPerSlide: 3, gap: 24 }
      }
    }"
  >
    <PagiflowSlide>Slide 1</PagiflowSlide>
    <PagiflowSlide>Slide 2</PagiflowSlide>
    <PagiflowSlide>Slide 3</PagiflowSlide>
  </Pagiflow>
</template>

Methods

Vue wrappers expose navigation/state helpers directly, and full core methods are available through the underlying instance (slider.value?.instance in component ref or instance.value in usePagiflow). Component also supports tag prop (default div).

.next()
Go to the next slide.
.prev()
Go to the previous slide.
.goTo(index, options?)
Jump to slide by zero-based index. Options: { silent: false, instant: false }.
.play()
Resume autoplay.
.pause()
Pause autoplay or autoScroll.
.resume()
Resume from paused state (autoplay/autoScroll). Available on core instance.
.togglePlayPause()
Toggle between play and pause.
.setOptions(newOptions, rebuild?)
Update options at runtime. Rebuilds if structural options change.
.reInit(newOptions?)
Completely reinitialize the slider.
.html(content?)
Get or set slide HTML. Rebuilds the slider if new content is provided. Available on core instance.
.destroy()
Destroy slider instance and remove internal listeners. Available on core instance.
.onSlideChange(callback)
Subscribe to index changes on core instance (used internally by Vue emits/hook state).
.index / .slides / .currentPerSlide
Readable instance state values on core instance.

Events

Hook into slider lifecycle with Vue's emits.

slideChange and ready events

slideChange emits active index changes. ready emits the core instance after mount.

<template>
  <Pagiflow @ready="onReady" @slideChange="onSlideChange">
    <PagiflowSlide>Slide 1</PagiflowSlide>
    <PagiflowSlide>Slide 2</PagiflowSlide>
  </Pagiflow>
</template>

<script setup>
function onReady(instance) {
  console.log('Pagiflow instance:', instance);
}

function onSlideChange(index) {
  console.log('Active index:', index);
}
</script>

All Options Reference

Complete list of all configuration options. Defaults can change across releases; verify runtime defaults against the current core version when needed.

Option Type Default Description
tag (component prop) string 'div' Root element tag rendered by <Pagiflow>.
direction string 'horizontal' Slide axis: 'horizontal' or 'vertical'.
itemsPerSlide number 1 Visible slides at once.
slidesToScroll number 1 Steps per navigation click.
gap number 8 Pixels between slides.
height string|number auto Viewport height (Required when using vertical, fade, or thumbnails mode.).
startIndex number 0 Initial slide index.
loop boolean false Infinite loop with DOM clones.
speed number 400 Transition duration (ms).
animate boolean true Enable CSS transitions.
fade boolean false Crossfade instead of slide.
nav boolean false Show built-in prev/next buttons.
navDisabledEnd boolean false Disable (not hide) buttons at ends.
navigation object null External buttons { prev, next }.
prevIcon string '‹' Prev button HTML.
nextIcon string '›' Next button HTML.
prevPosition string|obj null Absolute position for prev button.
nextPosition string|obj null Absolute position for next button.
paginate boolean false Show pagination dots.
paginationPosition string|obj null Custom pagination position.
autoplay boolean false Auto-advance slides.
autoplayDelay number 3000 Delay between auto advances (ms).
pauseOnHover boolean true Pause autoplay on hover.
autoScroll boolean false Continuous marquee scrolling.
autoScrollSpeed number 0.5 Pixels per animation frame.
autoScrollDirection string 'left' 'left' or 'right'.
swipeThreshold number 60 Min swipe distance to trigger change.
grid boolean false Enable grid mode per slide.
gridColumns number 2 Grid column count.
gridFill boolean false Fill last page with recycled items.
thumbnails.enabled boolean false Show thumbnail strip.
thumbnails.position string 'bottom' top / bottom / left / right.
thumbnails.thumbWidth number 80 Thumbnail width in px.
thumbnails.gap number 5 Gap between thumbnails.
thumbnails.sidebarHeight string null Sidebar height for left/right mode.
centerMode boolean false Center active slide with peeking neighbors.
centerPadding number|string 0 Side padding for center mode.
rtl boolean false Right-to-left mode.
keyboard boolean false Arrow key navigation.
lazyLoad boolean false IntersectionObserver image lazy load.
sync string|inst null Selector or instance to sync with.
responsive object {} Breakpoint → options map.
html str|arr null Inject initial slide HTML content during initialization.

See All Docs for the full list of 30+ options.

Nuxt 3 Only (SSR)

Pagiflow Vue Nuxt support is for Nuxt 3 only. Render slider UI on the client with <ClientOnly>.

Nuxt 3 ClientOnly Example
<script setup>
import { Pagiflow, PagiflowSlide } from 'pagiflow/vue';
import 'pagiflow/css';
</script>

<template>
  <ClientOnly>
    <Pagiflow :options="{ nav: true, loop: true }">
      <PagiflowSlide>Slide 1</PagiflowSlide>
      <PagiflowSlide>Slide 2</PagiflowSlide>
    </Pagiflow>
  </ClientOnly>
</template>

If you use usePagiflow, bind sliderRef only after mount and keep options stable for predictable hydration. Nuxt 2 and older Nuxt versions are not supported in this integration guide.

Best Practices

Recommended patterns for performance, accessibility, and maintainable Vue slider code.

Performance: Keep slide DOM light, prefer responsive itemsPerSlide, and enable lazyLoad for image-heavy carousels.
Accessibility: Enable keyboard for arrow navigation, use meaningful image alt text, and ensure custom nav buttons have accessible labels.
State updates: For frequent option changes, use setOptions(opts, false) when rebuild is not required; use reInit() only for structural changes.
Sync sliders: Prefer syncing with stable selectors or direct instance references once both sliders are mounted.

Troubleshooting

Quick fixes for common Vue carousel integration issues.

Slider does not initialize: Confirm import 'pagiflow/css' is present and package is installed with npm i pagiflow.

Methods do nothing: Wait for @ready or check that slider.value?.instance / instance.value is not null yet.

Layout looks wrong on first render: Ensure container has visible width at mount time; avoid hidden parents during initialization.

Nuxt hydration mismatch: Use Nuxt 3 with <ClientOnly> and avoid server-only DOM assumptions.

External nav selectors not working: Verify selectors resolve to existing elements and are unique on the page.

Frequently Asked Questions

Common questions about using pagiflow/vue.

Run npm i pagiflow, then import from pagiflow/vue.
Yes. Use usePagiflow with a raw HTMLElement ref, or use a component ref with <Pagiflow> for standard Vue integration.
The component emits @slideChange and @ready events.
Use a component ref and call wrapper methods such as next(), prev(), goTo(), setOptions(), and reInit(). For full core methods, use the emitted/returned instance.
No. Pagiflow Vue compatibility here is for Nuxt 3 only. Use <ClientOnly> and initialize on the client side.
<Pagiflow> is the standard component API with emits and ref helpers. usePagiflow gives Composition API control over a raw HTMLElement ref.