Polling in Inertia

Basic polling with no options¶

To demonstrate the basic use of polling in Inertia, let's take a page that shows the current date and time passed as a prop. This will allow us to see a refresh in action with little work.

return inertia()->render('DateTime', [
    'datetime' => now()->toDateTimeString()
]);

And here's how we'd dump that datetime prop on the page:

<script setup>
defineProps({
    datetime: String
})
</script>

<template>
    <div>
        {{ datetime }}
    </div>
</template>

Ok, let's immediately bring in the usePoll helper and see what happens.

<script setup>
import { usePoll } from '@inertiajs/vue3'

defineProps({
    datetime: String
})

usePoll(1000)
</script>

<template>
    <div>
        {{ datetime }}
    </div>
</template>

You'll be suprised to know, that's it. Inertia will now re-request all of the props passed to this page with an inertial of 1000ms (1 second) (and all your globals, but we'll get to that next).

usePoll router options¶

Behind the scenes, usePoll is just reloading your data with Inertia's router, which means you can pass any options you usually would.

This is really important. Using usePoll on its own will refresh all props on the page and those defined in HandleInertiaRequests (stuff like your currently authenticated user). It's unlikely you want to refresh everything, so here's how you'd define which props you want to poll for:

<script setup>
import { usePoll } from '@inertiajs/vue3'

usePoll(1000, {
    only: ['datetime']
})
</script>

By providing only here, we're now just polling for the datetime prop. Because this is an array, add all the props you want to poll for here.

Aside from this, you can pass any other options here, too, that the router would normally accept.

autoStart and controlling polling¶

By default, usePoll will immediately kick in. Suppose you'd like to turn this off (or control it yourself). In that case, the third argument to usePoll allows you to control specific poll options.

Here's how to disable autostart:

usePoll(5000, {
    only: ['datetime'],
}, {
    autoStart: false,
})

Why is this useful? Well, usePoll exposes two methods to stop and start polling programmatically. Here's an example:

<script setup>
import { usePoll } from '@inertiajs/vue3'

const { start, stop } = usePoll(5000, {
    only: ['datetime'],
}, {
    autoStart: false
})

defineProps({
    datetime: String
})
</script>

<template>
    <div>
        <div>{{ datetime }}</div>

        <div>
            <button v-on:click="start">Start polling</button>
            <button v-on:click="stop">Stop polling</button>
        </div>
    </div>
</template>

By invoking start or stop, you can manually control polling from your template or within your script. We cover a more practical example in the New in Inertia course if you'd like to see this in action.

Throttling polling¶

When a browser window isn't in view, making polling requests at the same rate doesn't make sense because a user won't be able to see updates.

By default, Inertia will throttle polling by 90% (at the time of writing) when the browser window isn't in view. To disable this, you can use the keepAlive option to always poll at the duration you specify, regardless of whether the window is in view:

usePoll(5000, {}, {
    keepAlive: true,
})

Want to learn more?¶

So, that's the basics of polling in Inertia! This new helper means we don't have to write any code to manually refresh props.

We cover more about polling in the New in Inertia course here and everything else you'll find in Inertia v2 — with plenty of practical examples!