ELWでエンジニアをしております。井立田です。
概要
- nuqsとは
- クエリパラメータとアプリケーション状態を型安全に同期するためのライブラリ
- hooks経由でクリパラメータと同期されたstateを扱える
- クエリパラメータに型を定義できる
- server componentでも扱える
- ライブラリのサイズは約 4.15 kB と軽量
nuqs.47ng.com
使い方
layout.tsx
import { NuqsAdapter } from 'nuqs/adapters/next/app'
import { ReactNode } from 'react'
export default function RootLayout({
children
}: {
children: ReactNode
}) {
return (
html
body
NuqsAdapter{children}NuqsAdapter
body
html
)
}
client component
- useQueryState
- ローカルstateとクエリパラメータを同期する
- 第一引数にクエリパラメータのkey名、第二引数にparserで型を指定する
nuqs.47ng.com
- クエリ文字列がURLに存在しない場合はnullを返す
- default値はdefaultValueオプション、parserの
.widhDEfault メソッドで指定できる
'use client'
import { parseAsInteger, parseAsString, useQueryStates } from 'nuqs'
export function Demo() {
const [name, setName] = useQueryState('name', parseAsString.withDEfault(''))
return (
div
input
value={name || ''}
onChange={e => setQuery({ name: e.target.value || null })}
div
)
}
'use client'
import { parseAsInteger, parseAsString, useQueryStates } from 'nuqs'
export function Demo() {
const [query, setQuery] = useQueryStates({
name: parseAsString.withDefault(''),
age: parseAsInteger.withDefault(0),
})
return (
div
input
value={query.name || ''}
onChange={e => setQuery({ name: e.target.value || null })}
input
value={query.age || ''}
onChange={e => {
const value = e.target.value
setQuery({ age: value ? parseInt(value) : null })
}}
div
)
}
server componentでの利用
import {
createSearchParamsCache,
parseAsInteger,
parseAsString
} from 'nuqs/server';
export const searchParamsCache = createSearchParamsCache({
name: parseAsString.withDefault(''),
age: parseAsInteger.withDefault(0),
});
type PageProps = {
searchParams: URLSearchParams;
};
export default async function Page({ searchParams }: PageProps) {
const { name, age } = await searchParamsCache.parse(searchParams);
return (
div
h1Profileh1
pName: {name}p
Age
div
);
}
function Age() {
const age = searchParamsCache.get('age');
return spanThe entered age is {age} years old.span;
}
オプション
デフォルトではnuqsはクエリパラメータを以下のように更新する
- クライアント側でのみクエリ更新を行い、サーバーには通知しない
- 現在の履歴エントリを置き換える。ブラウザバックに対応。
- ページのトップにスクロールしない
上記の挙動はオプションで設定可能
- オプションの指定方法
- フックレベルで指定
- 更新関数呼び出し時に指定
const [state, setState] = useQueryState(
'foo',
parseAsString.withOptions({ history: 'push' })
)
setState('foo', { scroll: true })
nuqs.47ng.com
メリットとデメリット
- メリット
- 軽量かつ簡単
- クエリパラメータの型変換や同期を自前で実装する必要がない
- デメリット
- ローカルstateになるため、クエリパラメータをグローバルstateで管理したい場合は不向き
