Skip to main content

useRouter

ts
import { useRouter } from 'solito/router'
ts
import { useRouter } from 'solito/router'

This hook lets you navigate from one screen to another across platforms, using nothing but URLs and Next.js Url objects.

Usage

tsx
const { push, replace, back, parseNextPath } = useRouter()
 
const onPress = () => {
push('/')
}
const onGoBack = () => {
back()
}
tsx
const { push, replace, back, parseNextPath } = useRouter()
 
const onPress = () => {
push('/')
}
const onGoBack = () => {
back()
}

Returns

push

Follows the exact same API as push returned by Next.js useRouter hook.

Basic example

tsx
const { push } = useRouter()
 
const onOpenArtist = () => {
push('/artists/drake')
 
// or, you can do:
push({
pathname: '/artists/[slug]',
query: {
slug: 'drake',
},
})
}
tsx
const { push } = useRouter()
 
const onOpenArtist = () => {
push('/artists/drake')
 
// or, you can do:
push({
pathname: '/artists/[slug]',
query: {
slug: 'drake',
},
})
}

Passing query parameters

Use the query object to pass any query parameters to the next screen.

tsx
const { push } = useRouter()
 
const onOpenArtist = () => {
push({
pathname: '/artists/drake',
query: {
initialOfferAmount: 500000,
},
})
}
tsx
const { push } = useRouter()
 
const onOpenArtist = () => {
push({
pathname: '/artists/drake',
query: {
initialOfferAmount: 500000,
},
})
}

solito will automatically stringify this into a URL for you on Native, making it easy for React Navigation.

replace

Just like push(), this follows the exact same API as Next.js useRouter().replace.

It takes the exact same arguments as push.

tsx
const { replace } = useRouter()
 
const onOpenArtist = () => {
replace({
pathname: '/artists/drake',
query: {
initialOfferAmount: 500000,
},
})
}
tsx
const { replace } = useRouter()
 
const onOpenArtist = () => {
replace({
pathname: '/artists/drake',
query: {
initialOfferAmount: 500000,
},
})
}

Limitation

On iOS and Android, this function doesn't call actually replace(). Instead, it calls linkTo from React Navigaton.

This is because React Navigation doesn't currently offer an API to replace a current route with a URL.

If this is a big need for you, please open an issue.

parseNextPath

This function is used under the hood by push and replace to turn a Next.js Url object (or string) into a valid URL string. It's exposed in case you're doing something special.

It takes a Next.js Url object (or a string) and returns a stringified URL.

It's useful if you want to provide stable keys to lists of URLs, for instance.

API

ts
parseNextPath(url: string | Url): string
ts
parseNextPath(url: string | Url): string
ts
const path = parseNextPath({
pathname: '/artists',
})
ts
const path = parseNextPath({
pathname: '/artists',
})

Arguments

It has a single argument, which is either a string or a Url object. A Url object is the same as the first argument for push.

Returns

string

Usage

Imagine this example:

ts
const { parseNextPath } = useRouter()
 
const href = parseNextPath({
pathname: '/artists/[slug]',
query: {
slug: 'drake',
},
})
ts
const { parseNextPath } = useRouter()
 
const href = parseNextPath({
pathname: '/artists/[slug]',
query: {
slug: 'drake',
},
})

Here, href will become /artists/drake.

If you add other query parameters, they will be added to the end of the URL:

ts
const { parseNextPath } = useRouter()
 
const href = parseNextPath({
pathname: '/artists/[slug]',
query: {
slug: 'drake',
initialOfferAmount: 500_000,
},
})
ts
const { parseNextPath } = useRouter()
 
const href = parseNextPath({
pathname: '/artists/[slug]',
query: {
slug: 'drake',
initialOfferAmount: 500_000,
},
})

In this case, href is /artists/drake?initialOfferAmount=500000.

Basic example

tsx
const { parseNextPath } = useRouter()
 
const list = artists.map((artist) => {
const href = parseNextPath({
pathname: '/artists/[slug]',
query: {
slug: artist.slug,
},
})
 
return <Artist href={href} key={artist.slug} />
})
tsx
const { parseNextPath } = useRouter()
 
const list = artists.map((artist) => {
const href = parseNextPath({
pathname: '/artists/[slug]',
query: {
slug: artist.slug,
},
})
 
return <Artist href={href} key={artist.slug} />
})