A Vue 3 composable for offline-first syncing. Save data while offline and automatically sync it when back online. Uses IndexedDB for offline storage.
- Auto-sync when online
- Custom API endpoint
- Uses IndexedDB for offline storage
- Bulk or individual syncing
- Configurable retry policy for failed requests
npm install vue-offline-sync
Here’s a basic implementation example
<script setup>
import {ref} from 'vue';
// 1. Import library
import {useOfflineSync} from 'vue-offline-sync';
const formData = ref({name: '', message: ''});
// 2. Initialize
const {state, saveOfflineData} = useOfflineSync({
url: 'https://myapi.com/sync',
// method: 'POST', // optional
// headers: {Authorization: 'Bearer your-token'}, // optional
// bulkSync: false, // optional
// uniqueKeys: ['name'], // optional
// retryPolicy: { maxAttempts: 3, delayMs: 1000 }, // optional
});
const submitData = async () => {
if (!formData.value.name || !formData.value.message) return;
// 3. Pass your data to this method.
await saveOfflineData({name: formData.value.name, message: formData.value.message});
formData.value = {name: '', message: ''};
};
</script>
<template>
<div>
<h2>Vue Offline Sync Example</h2>
<p>Status: <strong>{{ state.isOnline ? 'Online' : 'Offline' }}</strong></p>
<form @submit.prevent="submitData">
<input v-model="formData.name" placeholder="Your Name" required/>
<textarea v-model="formData.message" placeholder="Your Message" required></textarea>
<button type="submit">Save</button>
</form>
</div>
</template>
Option | Type | Required | Default | Description |
---|---|---|---|---|
url |
String | ✅ Yes | undefined |
API endpoint to sync data |
method |
String | ❌ No | "POST" | HTTP method (e.g., "POST", "PUT", etc.) |
headers |
Object | ❌ No | {} | Additional headers (e.g., authentication token) |
bulkSync |
Boolean | ❌ No | false | Set to true if your API accepts batch sync requests |
uniqueKeys |
String[] | ❌ No | undefined |
Specifies the columns that must have unique values across all entries. If any of the defined columns contain duplicate values, the entry will be rejected. |
retryPolicy |
Object | ❌ No | {maxAttempts: 1, delayMs: 1000} |
Configures automatic retries for failed requests. See Retry Policy below. |
State | Type | Description |
---|---|---|
state.isOnline |
Boolean |
true when online, false when offline |
state.offlineData |
Array | Data stored in IndexedDB during offline mode |
state.isSyncInProgress |
Boolean | Can be used to indicate a loading state in the UI, informing the user that syncing is in progress |
Method | Description |
---|---|
saveOfflineData(object) | Saves data to IndexedDB when offline, or syncs directly when online |
syncOfflineData() | Manually triggers syncing of offline data |
The retryPolicy
option allows configuring automatic retries for failed API requests.
Property | Type | Default | Description |
---|---|---|---|
maxAttempts |
Number | 1 |
Maximum number of retries before failing |
delayMs |
Number | 1000 |
Delay (in milliseconds) between retry attempts |
Example Usage:
const {state, saveOfflineData} = useOfflineSync({
url: 'https://myapi.com/sync',
retryPolicy: {
maxAttempts: 5,
delayMs: 2000,
}
});
💡 If a request fails, it will retry up to 5 times with a 2-second delay between each attempt.
Note: The individual syncing is being used by default.
✔ Sends all offline data as one request
✔ Recommended for APIs that support bulk inserts
Example Requests
[
{
"name": "Name A",
"message": "Hello!"
},
{
"name": "Name B",
"message": "Hey there!"
}
]
✔ Sends each offline entry separately
✔ Recommended for APIs that only accept single requests
Example Requests
{
"name": "Name A",
"message": "Hello!"
}