<VueEasyPullRefresh>

Template structure

This is the simplified template of the <VueEasyPullRefresh>. It will be helpful for understanding the naming of props.

<template>
    <VueEasyPullRefresh>
        <!-- -->
    </VueEasyPullRefresh>
</template>

Props

isRefreshContent

• Type: Boolean
• Default: true
• Description: Enables or disables automatic content refresh inside the wrapper component. When enabled, the inner content will be reloaded during the refresh action.

---

isAppearAnimation

• Type: Boolean
• Default: true
• Description: Enables or disables the fade-in animation of the content. This prop is only applicable when isRefreshContent is set to true.

---

isFreezeContent

• Type: Boolean
• Default: false
• Description: Freezes the content swap animation until the loader is fully hidden. When enabled, the entering content stays invisible and the leaving content stays put while the loader is visible; both opacity animations only start after the settled event. Useful when you want the content transition to happen after the pull-to-refresh UI has returned to its idle state, rather than overlapping with the loader hiding. This prop is only applicable when isRefreshContent is set to true.

Behavior matrix

isAppearAnimation	isFreezeContent	Effect
true	false	Fade animation starts immediately when the content key changes (default).
true	true	Old content stays visible, new content stays hidden until the loader finishes hiding; then the fade happens.
false	false	Content swap without fade, overlapping with loader hide.
false	true	Content swap without fade, deferred until the loader finishes hiding.

Example

<script setup>
import { VueEasyPullRefresh } from 'vue-easy-pull-refresh';

function loadFeed() {
    return fetch('/api/feed').then(r => r.json());
}

function onSettled() {
    // UI is idle again — safe to focus an element, resume a video, etc.
}
</script>

<template>
    <VueEasyPullRefresh
        :initial-queue="loadFeed"
        :is-freeze-content="true"
        @settled="onSettled"
    >
        <FeedList />
    </VueEasyPullRefresh>
</template>

With isFreezeContent the user sees the old feed until the loader has fully rolled up; only then does the new feed fade in. This avoids the "content flickering while the loader is still on screen" effect.

---

isDisabled

• Type: Boolean
• Default: false
• Description: Enables or disables the functionality of the component. When set to true, the component will not respond to user gestures, effectively disabling the pull-to-refresh behavior.

---

pullDownThreshold

• Type: Number
• Default: 64
• Description: Sets the height the user needs to pull down to trigger the refresh action. This value determines how sensitive the pull-to-refresh gesture is, and can be adjusted to customize the experience.

---

directionLockAngle

• Type: Number
• Default: 30
• Description: Max angle (in degrees) from the vertical axis that still counts as a pull-down. Larger angles are treated as horizontal and ignored until the gesture ends — this prevents nested carousels, tabs, and horizontal sliders from hijacking a refresh when the user drifts slightly downward. Set to 90 to disable the lock entirely.

---

initialQueue

• Type: Function returning Promise
• Default: undefined
• Description: Async callback that runs on every refresh. The loader stays visible until the promise resolves. Use this when you have a single task in the parent component instead of wiring useEasyPullRefresh in a child.

Events

started

• Description: Emitted as soon as the pull-down gesture starts moving the content, before pullDownThreshold is reached. Useful for reacting to the very beginning of the interaction — dimming a header, pausing a carousel, or showing a hint.

(e: 'started') => void

reached

• Description: Emitted when the pull-down gesture reaches pullDownThreshold and the refresh starts. Fires before queued tasks begin — use settled when you need to react after everything is done.

(e: 'reached') => void

settled

• Description: Emitted when the refresh animation is fully completed and the component has returned to its idle state. Useful for triggering actions that require the UI to be stable again.

(e: 'settled') => void

Example Usage:

<VueEasyPullRefresh
   @started="handleStart"
   @reached="handleReached"
   @settled="handleSettled"
/>

Slots

default

• Description: The default slot is used to insert the main content inside the VueEasyPullRefresh component. This is the content that will be refreshed when the pull-to-refresh gesture is triggered.

loader (optional)

• Description: The loader slot allows you to customize the loading indicator that appears when the content is being refreshed. If no custom loader is provided, the default loader will be used.