Consolidate Router State Access

[ryanflorence]

Right now you access active, pending, and transitioning states from a bunch of different hooks. This proposal hopes to consolidate them all into a simpler API.

Today

Accessing Current States

let location = useLocation()
let params = useParams()
let [searchParams] = useSearchParams()
let matches = useMatches()
let type = useNavigationType()

<NavLink to={path}>{({ isActive }) => isActive}</NavLink>

Accessing Pending States

let navigation = useNavigation()
navigation.location

// have to construct search params
let searchParams = new URLSearchParams(
  navigation.location.search,
)

// no access
let params = undefined
let type = undefined

// access to form stuff (rarely used, fetchers usually better)
navigation.formAction // etc.

<NavLink to={path}>{({ isPending }) => isPending}</NavLink>

Accessing View Transition States

let state = useViewTransitionState(to)

<NavLink to={path}>
  {({ isTransitioning }) => isTransitioning}
</NavLink>

Proposal: Consolidate into one hook

All of those hooks are either accessing active/pending states or matching against a path and providing active/pending states. We can do this with one hook.

type RouterStateVariant = {
  location: Location
  searchParams: URLSearchParams
  params: Params
  matches: Matches
}

type RouterState = {
  active: RouterStateVariant
  pending: null | RouterStateVariant
  transitioning: boolean
}

let { active, pending, transitioning } = useRouterState()

// user clicks a link, both active and pending could have values
active.location
pending.location

By providing a path to the hook, we can match against it to determine the states, and even provide better types

type RouterStateVariant<Path> = {
  location: Location<Path>
  searchParams: URLSearchParams<Path>
  params: Params<Path>
  matches: Matches<Path>
  type: NavigationType // Pop, Push, Replace
}

type RouterState<Path> = {
  active: null | RouterStateVariant<Path>
  pending: null | RouterStateVariant<Path>
  transitioning: boolean
}

let { active, pending, transitioning } =
  useRouterState('/projects/:id')

// the url is /projects/123
active.params.id
active.location // etc.
pending === null

// the url is /projects, user clicked /projects/123
active === null
pending.params.id
pending.location

Deprecations

This one hook can deprecate all eight of these:

• useLocation
• useSearchParams
• useParams
• useTransitionState
• useNavigation
• useMatches
• useMatch(pattern)
• useNavigationType

Refactor

Probably some potential refactoring to simplify the code and have the deprecated hooks (and NavLink) use the new hook underneath.

[gustavopch]

Love seeing the API surface shrinking.

[pimjansen]

Love seeing the API surface shrinking.

Not fully agree on this. Love seeing the API simplified in usage however accessing these API's directly could also benefit a lot of use cases. Putting it all into a single solution would probably make it way too opiniated.

But love to see the addition to simplify the usage in general

[gustavopch]

Instead of having to remember which exact hook does what you need, you can simply call useRouterState and then use Ctrl+Space to find what you're looking for. Bonus: there's less to learn if you're new to React Router.

I think it's just a different opinion, but not a "more opinionated" opinion. OTOH, keeping both the unified hook and separated hooks would be bad for codebase consistency and would bloat the API with new stuff to learn and remember instead of simplifying it.