| name | jeff-url-state-nuqs |
| description | Jeff's URL state conventions using nuqs. Use when working on pagination, search, filters, date/view modes, or route-level overlays. |
Jeff's URL State with nuqs
Use URL query state as the source of truth for route-level, shareable state.
Apply when
- Table pagination/search/filter work.
- Date or view-mode switching.
- Route-level dialog/sheet/alert visibility.
Required conventions
- Use
nuqs query state for data-fetch-affecting state.
- Always set
clearOnDefault: true for clean URLs.
- Reset page to
1 when search/filter/date changes.
- Route-level overlays must be URL-driven, not local open-state.
Standard keys
p: page
ps: page size
q: search query
d: single date (yyyy-MM-dd)
df: date from
dt: date to
v: view mode
Common filter keys:
fp positions
fl locations
fd departments
fs statuses
fss system statuses
fas attendance statuses
fam attendance methods
fsn shift names
URL vs local state
Keep in URL:
- page/pageSize/search
- filters
- date/date-range
- view mode
- route-level overlay mode/id
Keep local:
- ephemeral UI (hover, dropdown search input, drag state)
- file objects and upload intermediates
- table row expansion/selection unless explicitly URL-driven by product requirement
Validation checklist