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

• • Back/Forward navigation restores state.
• • Shared URL reproduces the same screen state.
• • Defaults are omitted from URL output.