FRENVersion française

Lists

Pull to refresh

Tirer pour rafraîchir

Demo

Loading demo…

A touch gesture: pull the list down from the top, let go, and the content reloads. It is used on lists that change often, mostly on mobile.

Story

Did you know

Loren Brichter invented it for Tweetie, a Twitter client, around 2008-2009. Twitter bought the app and was granted a patent on the gesture in 2013, while pledging to use it only defensively. Brichter himself later said he found the gesture a bit dated.

Timeline

  1. 2009Loren Brichter introduces it in Tweetie 2.
  2. 2010Twitter acquires Tweetie, which becomes the official app.
  3. 2013Twitter is granted a patent on pull-to-refresh.
  4. 2010sAndroid (SwipeRefreshLayout) and iOS (UIRefreshControl) build it in natively.

Vocabulary

Names

FR
Tirer pour rafraîchir, glisser pour actualiser, tirer pour actualiser
EN
Pull to refresh, pull-down to refresh, swipe to refresh, PTR

Common uses

  • Feeds and inboxes on mobile
  • Lists whose content changes often
  • Apps with no visible Refresh button

Often paired with

The components it usually sits with, by page type, in reading order.

Code

<button id="refresh">Refresh</button>
<p id="status" role="status"></p>
<ul id="list" style="overflow-y: auto; overscroll-behavior-y: contain">…</ul>

<script>
  const list = document.querySelector('#list')
  const status = document.querySelector('#status')
  let startY = null
  let offset = 0

  // At the top, leave downward pulls to JS; elsewhere, scroll normally
  const sync = () => (list.style.touchAction = list.scrollTop === 0 ? 'pan-x pan-down' : 'pan-x pan-y')
  list.addEventListener('scroll', sync, { passive: true })
  sync()

  list.addEventListener('pointerdown', (e) => { if (list.scrollTop === 0) startY = e.clientY })
  list.addEventListener('pointermove', (e) => {
    if (startY === null) return
    offset = Math.max(0, (e.clientY - startY) * 0.5) // elastic damping
    list.style.translate = `0 ${offset}px`
  })
  const release = (e) => {
    const pulled = startY !== null && e.type === 'pointerup' && offset > 60
    startY = null
    offset = 0
    list.style.translate = ''
    if (pulled) refresh()
  }
  list.addEventListener('pointerup', release)
  list.addEventListener('pointercancel', release)
  document.querySelector('#refresh').addEventListener('click', refresh)

  async function refresh() {
    status.textContent = 'Refreshing…'
    const items = await fetch('/api/latest').then((r) => r.json())
    list.prepend(...items.map((t) => Object.assign(document.createElement('li'), { textContent: t })))
    status.textContent = `${items.length} new items`
  }
</script>

Good to know

  • Chrome on Android and Safari on iOS already pull-to-refresh the page: overscroll-behavior-y: contain turns that off when you build your own.
  • Damp the movement (×0.5) for an elastic feel, and animate translate rather than top or margin.
  • Only start the gesture when the list is at the very top (scrollTop === 0). Otherwise it fights with normal scrolling.
  • On touch, the browser keeps the gesture and fires pointercancel. The Pointer Events spec suggests touch-action: pan-x pan-down at the top of the list. Support for the directional values varies: test on iOS.

Accessibility

Must have

  • Always offer another way to refresh: a visible button. The gesture is not discoverable, and a drag needs a non-drag alternative (WCAG 2.5.7).
  • Announce the state in a role="status" region: "Refreshing…", then "3 new messages".

Often forgotten

  • A spinner alone says nothing. An aria-label on a <span> with no role is not reliably read: use the status region.
  • Don't steal focus. New items land at the top: leave focus where it is and announce how many arrived.

Nice to have

  • With prefers-reduced-motion, drop the elastic effect and keep only the indicator.
  • Show the time of the last update next to the button.

Who uses it