Allow passing URL object to useRouter functions

[hugotiger]

Goals

1. Align the API between next/link and useRouter from next/navigation
2. Avoid error-prone string manipulation in programmatic navigation.
3. Make Next.js App Router easier to adopt for users coming from the Pages router or React Router / Remix.

Non-Goals

1. Validation/handling of incorrectly formatted URL parts (e.g. search)
2. Enforcement of any specific encoding standard, e.g. for search param array values.

Background

I've found it quite confusing that the Link component from next/link accepts pretty much all of the parameters of the URL class, but the programmatic functions from useRouter does not. In the pages router this was supported, and in other frameworks/libraries such as React Router it also is.

Right now string manipulation has to be done in user-land, which is quite error prone. Also to my understanding often it's preferable to use window.location.search if programmatic navigations in callbacks, to avoid having useSearchParams opting out of static rendering.

Here's some examples:

Example 1: Forwarding current search params

router.push(`/new-path${window.location.search}`)

This example is not that bad, but it's in my experience quite error prone doing string manipulations like this. Also any issues would not be immediately noticeable unless you actively trigger the programmatic navigation.

Example 2: Setting search params and hash

router.push(`/new-path#some-id?newQuery=true`)

Here it gets a little worse in my opinion... I believe a lot of devs don't know top of mind if the hash or search string should come first.

Example 3: With URLSearchParams

const searchParams = useSearchParams()

const handleCallback = () => {
  // Ugh... the API is different so we manually have to handle the "?"
  const search = searchParams.toString() ? `?${searchParams.toString()}` : ''
  router.push(`/new-path${search}`)
}

Proposal

I suggest that the programmatic navigation functions should support the API class, or at least a subset of it. Alternatively it could support the UrlObject which is what the Link component does, but the downside with that is that it doesn't seem to support passing URLSearchParams.

With this suggestion the code examples from earlier could instead look something like this:

Example 1: Forwarding current search params

router.push({ pathname: '/new-path', search: window.location.search })

Example 2: Setting search params and hash

router.push({ path: '/new-path', hash: '#some-id', search: '?newQuery=true' })

Example 3: With URLSearchParams

const searchParams = useSearchParams()

const handleCallback = () => {
  router.push({ pathname: '/new-path', searchParams })
}

---

I'm definitely interested in contributing! So something along the lines of what I've proposed sounds good, I can (attempt) making a PR for it 😄

[xabierlameiro]

This is an excellent feature request that addresses a real inconsistency between the Link component and useRouter APIs! Based on the official Next.js documentation and current implementation patterns, here are some workarounds and thoughts on your proposal.

Current Workarounds

1. Using Object-style navigation (similar to Link)

You can already use an object-style approach with useRouter.push(), but it's more limited than the Link component:

import { useRouter } from 'next/navigation'

const router = useRouter()

// This works for basic cases
const navigateWithQuery = () => {
  // You still need to manually construct the URL
  const searchParams = new URLSearchParams(window.location.search)
  searchParams.set('newQuery', 'true')
  
  router.push(`/new-path?${searchParams.toString()}`)
}

2. Helper function approach

You can create a utility function to bridge this gap:

import { useRouter } from 'next/navigation'

interface NavigationOptions {
  pathname: string
  search?: string
  searchParams?: URLSearchParams
  hash?: string
  scroll?: boolean
}

const useEnhancedRouter = () => {
  const router = useRouter()
  
  const pushWithObject = (options: NavigationOptions) => {
    let url = options.pathname
    
    if (options.searchParams) {
      const params = options.searchParams.toString()
      if (params) url += `?${params}`
    } else if (options.search) {
      url += options.search.startsWith('?') ? options.search : `?${options.search}`
    }
    
    if (options.hash) {
      url += options.hash.startsWith('#') ? options.hash : `#${options.hash}`
    }
    
    router.push(url, { scroll: options.scroll ?? true })
  }
  
  return { ...router, pushWithObject }
}

Why This Feature Makes Sense

Your proposal aligns perfectly with web standards and developer expectations:

1. Consistency with Link component: The Link component already accepts object-style props (official docs)
2. Native URL API alignment: Using the standard URL constructor interface
3. Error reduction: Eliminates string manipulation errors
4. TypeScript benefits: Better type safety than string concatenation

Comparison with Current APIs

Link component (works today):

<Link href={{ 
  pathname: '/dashboard',
  query: { tab: 'analytics' }
}}>
  Dashboard
</Link>

Your proposed useRouter enhancement:

router.push({ 
  pathname: '/dashboard',
  search: '?tab=analytics',
  hash: '#section'
})

Implementation Considerations

Based on the official useRouter documentation, your proposal would need to:

1. Maintain backward compatibility: Keep existing string-based API
2. Support all current options: scroll parameter integration
3. Handle URLSearchParams: Direct support without manual .toString() conversion
4. Consistent behavior: Match Link component's object handling

Migration Benefits

This would make migrating from Pages Router much smoother, as developers expect similar object-based navigation APIs across React routing libraries.

Current Pages Router style:

router.push({
  pathname: '/dashboard',
  query: { tab: 'analytics' }
})

Your proposed App Router enhancement:

router.push({
  pathname: '/dashboard',
  searchParams: new URLSearchParams({ tab: 'analytics' })
})

This is a well-thought-out proposal that would significantly improve the developer experience. The inconsistency between Link and useRouter APIs is a valid pain point that your suggestion addresses elegantly! 🚀

[icyJoseph]

Interesting suggestion. I think, it is worth also exploring what you could do, as a dev in this situation, independently of what the framework decides to do.

I remember in Swift, building URLs was kind of easy and removed some of the rough edges, I think JavaScript URL constructor can also do that, to some extend

const toPath = (path, params = {}, hash = "") => {
  if (!path.startsWith("/")) path = `/${path}`

  const noop = "http://noop"; 
  const url = new URL(path, noop);

  const searchParams = new URLSearchParams(url.search); // in case the path had queries already
  for (const [key, value] of Object.entries(params)) {
    searchParams.set(key, value);
  }
  url.search = searchParams.toString();

  url.hash = hash.replace(/^#/, "");

  return url.toString().replace(noop, "");
};

toPath("/foo-bar?q=how", {page: 10}, "#how-to") // '/foo-bar?q=how&page=10#how-to'

I feel like this reduces quite a bit of the string manipulation otherwise needed. You'd still need to watch out for path shapes, and new URL possibly throwing (can it throw in this case?), perhaps query params collisions in some cases - but generally it looks good

[hugotiger]

This definitely works, but it'd be much nicer if this was handled in Next.js natively. I think the current setup is quite a paper cut since it breaks expectations/consistency, especially for people coming from other routers in the ecosystem (including the pages router).