useQuery

Category

Browser

Export Size

681 B

Last Changed

5 days ago

Shorthand for a reactive query parameter in window.location.search. Updates the URL query parameters when the value changes.

Demo

Usage

import { useQuery } from '@reause/core'

const [search, setSearch] = useQuery('search')

const [search, setSearch] = useQuery('search', 'foo') // or with a default value

const [page, setPage] = useQuery('page', '1', { transform: Number }) // or transforming value

console.log(search) // window.location.search's `search` param
setSearch('foobar') // history.replaceState({ query: { search: 'foobar' } })

Navigation Mode

By default, changes use history.replaceState(). Set mode: 'push' to use history.pushState() instead.

const [search, setSearch] = useQuery('search', '', { mode: 'push' })

Bidirectional Transform

You can provide separate get and set transforms for reading and writing values.

const [filters, setFilters] = useQuery('filters', [], {
  transform: {
    get: v => v ? v.split(',') : [],
    set: v => v.join(','),
  },
})

// Reading: 'a,b,c' -> ['a', 'b', 'c']
// Writing: ['a', 'b', 'c'] -> 'a,b,c'

Default Value Behavior

When the value equals the default value, the query parameter is removed from the URL.

const [page, setPage] = useQuery('page', '1')

setPage('2') // URL: ?page=2
setPage('1') // URL: (no page param, since it equals default)

Type Declarations

export type RouteQueryValueRaw = string | number | boolean | null | (string | number | boolean | null)[]

export interface UseQueryOptions<T, K> {
    mode?: 'replace' | 'push';
    transform?: ((value: T) => K) | ({
        get?: (value: T) => K;
        set?: (value: K) => T;
    });
}

export function useQuery(name: string): [
    undefined | null | string | string[],
    (value: undefined | null | string | string[]) => void
]

export function useQuery<T extends RouteQueryValueRaw = string, K = T>(name: string, defaultValue?: T, options?: UseQueryOptions<T, K>): [
    K,
    (value: K) => void
]

Source

Source · Demo

Contributors

Changelog

v0.1.0 on

e608a - feat(ci): align CI, packaging and release with VueUse

33fdd - fix(core): widen useQuery T generic in useQuery demo (#210)

5bd54 - feat(core): implement useQuery (#210)