useParams

Category

Browser

Export Size

783 B

Last Changed

5 days ago

Shorthand for a reactive path parameter in window.location.pathname, matched against a pattern path template. Updates the URL path when the value changes.

Demo

Usage

import { useParams } from '@reause/core'

const [userId, setUserId] = useParams('userId', '-1', { pattern: '/users/:userId' }) // or with a default value

const [page, setPage] = useParams<string>('page', '1', { pattern: '/posts/:page', transform: Number }) // or transforming value

console.log(userId) // the `userId` segment of window.location.pathname
setUserId('100') // history.replaceState with `/users/100`

Pattern Matching

Upstream proxies route.params through vue-router, whose route config defines which path segments are params. Since this hook has no routing library, that config has to be passed explicitly as the pattern option: a path template whose :name segments capture the matching window.location.pathname segment, while plain segments must match literally.

const [userId, setUserId] = useParams('userId', '', { pattern: '/users/:userId' })

// URL `/users/42`        -> userId is '42'
// URL `/users/`          -> userId is '' (the default, empty capture)
// URL `/profile/42`      -> userId is '' (the default, no match)
// No pattern given       -> userId is '' (the default)

Navigation Mode

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

const [userId, setUserId] = useParams('userId', '', { pattern: '/users/:userId', mode: 'push' })

Bidirectional Transform

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

const [userId, setUserId] = useParams('userId', '', {
  pattern: '/users/:userId',
  transform: {
    get: v => v.toUpperCase(),
    set: v => v.toLowerCase(),
  },
})

// Reading: URL `/users/alice` -> 'ALICE'
// Writing: 'ALICE'            -> URL `/users/alice`

Default Value Behavior

When the value equals the default value (or is null), the param is removed from the URL.

const [userId, setUserId] = useParams('userId', 'guest', { pattern: '/users/:userId' })

setUserId('alice') // URL: /users/alice
setUserId('guest') // URL: /users/ (no param, since it equals default)

Type Declarations

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

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

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

export function useParams<T extends RouteParamValueRaw = string, K = T>(name: string, defaultValue?: T, options?: UseParamsOptions<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

dbd0b - feat(core): implement useParams (#200)