https://github.com/sectsect/use-placeholder-path
A custom React hook to retrieve placeholder path in Next.js App Router. An alternative to router.pathname.
https://github.com/sectsect/use-placeholder-path
app-router nextjs path pathname placeholder-path react userouter
Last synced: 1 day ago
JSON representation
A custom React hook to retrieve placeholder path in Next.js App Router. An alternative to router.pathname.
- Host: GitHub
- URL: https://github.com/sectsect/use-placeholder-path
- Owner: sectsect
- License: mit
- Created: 2024-08-10T05:26:03.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-04T06:32:27.000Z (3 months ago)
- Last Synced: 2026-01-30T12:40:05.705Z (2 months ago)
- Topics: app-router, nextjs, path, pathname, placeholder-path, react, userouter
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@sect/use-placeholder-path
- Size: 674 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @sect/use-placeholder-path
[](https://github.com/sectsect/use-placeholder-path/actions/workflows/release.yml) [](https://codecov.io/gh/sectsect/use-placeholder-path) [](https://github.com/sectsect/use-placeholder-path/actions/workflows/github-code-scanning/codeql)
A custom React hook to retrieve placeholder paths in Next.js App Router.
## Why Use This Hook?
Next.js 13+ App Router doesn't provide a built-in method to return the path of placeholder values, unlike `router.pathname` in Pages Router. This hook fills that gap, allowing you to get the placeholder path in the App Router, similar to how you would in the Pages Router.
### Easing the Transition from Pages Router
For developers migrating from Pages Router to App Router, this hook can significantly reduce the pain points associated with the transition. It provides a familiar way to access placeholder paths, making it easier to port existing code and maintain consistency in your application's routing logic. By offering functionality similar to `router.pathname`, `usePlaceholderPath` helps bridge the gap between the two routing systems, allowing for a smoother migration process and reducing the need for extensive refactoring of route-dependent code.
## Installation
```bash
npm install @sect/use-placeholder-path
# or
yarn add @sect/use-placeholder-path
# or
pnpm add @sect/use-placeholder-path
```
## Usage
```tsx
'use client';
import usePlaceholderPath from '@sect/use-placeholder-path';
const MyComponent = () => {
const placeholderPath = usePlaceholderPath();
return (
Current placeholder path: {placeholderPath}
);
}
export default MyComponent;
```
## API
```typescript
usePlaceholderPath(options?: UsePlaceholderPathOptions): string
interface UsePlaceholderPathOptions {
optionalCatchAllSegments?: string;
}
```
- `optionalCatchAllSegments`: (optional) The name of the optional catch-all segment. If provided, enables handling of top-level optional catch-all segments.
## Examples
1. Route: `/users/123/posts/456`
- Result: `/users/[userId]/posts/[postId]`
2. Catch-all Segments Route: `/blog/2024/08/15`
- Result: `/blog/[...slug]`
3. Optional Catch-all Segments Route: `/shop/a/b/c`
- Result: `/shop/[[...slug]]`
> [!NOTE]
> For Top-Level Optional Catch-all Segments, special handling may be required. See the **"Known Issues"** section for more details.
## Notes
- `usePlaceholderPath` requires the use of a [Client Component](https://nextjs.org/docs/app/building-your-application/rendering/client-components).
## Known Issues
### Detecting Top-Level Optional Catch-all Segments
Top-Level Optional Catch-all Segments are expected to return `/folderName/[[...segmentName]]`, but currently `/folderName` is returned.
- Expected: `/shop/[[...slug]]`
- Actual: `/shop`
This is due to the technical limitations in detecting Top-Level Optional Catch-all Segments in the Next.js App Router.
To address this limitation, we've introduced an optional configuration:
```typescript
const placeholderPath = usePlaceholderPath({
optionalCatchAllSegments: 'slug'
});
```
## Changelog
See [CHANGELOG](https://github.com/sectsect/use-placeholder-path/blob/main/CHANGELOG.md).
✌️
A little project by @sectsect