Skip to main content
The route() function is Ziggy’s primary helper for generating URLs from Laravel route names in JavaScript. It can return either a URL string or a Router instance depending on how it’s called.

​
Function Signature

function route(): Router;

function route(
  name: undefined,
  params: undefined,
  absolute?: boolean,
  config?: Config
): Router;

function route<T extends ValidRouteName>(
  name: T,
  params?: RouteParams<T> | ParameterValue,
  absolute?: boolean,
  config?: Config
): RouteUrl;

​
Parameters

​
name
string
The name of the route to generate a URL for. If omitted or undefined, returns a Router instance instead of a URL string.Example: 'posts.show', 'users.edit'
​
params
string | number | array | object
Route parameters to fill in the route’s URI template. Can be:
  • A single value (string/number) for routes with one parameter
  • An array of values in parameter order
  • An object with parameter names as keys
  • Model objects with id property or custom route key bindings
Example: 1, [1, 2], { post: 1, comment: 5 }, { post: { id: 1 } }
​
absolute
boolean
default:"true"
Whether to generate an absolute URL (including the origin) or a relative path.
  • true: Returns full URL like https://example.com/posts/1
  • false: Returns relative path like /posts/1
​
config
Config
Optional Ziggy configuration object. If not provided, uses the global Ziggy variable or attempts to load config from a #ziggy-routes-json script tag.Properties:
  • url: Application URL
  • port: Application port (or null)
  • defaults: Default parameter values
  • routes: Route definitions object
  • location: Override current location (for SSR)

​
Return Value

  • When called with a route name: Returns a string containing the generated URL
  • When called without arguments or with name as undefined: Returns a Router instance for advanced usage

​
Examples

​
Basic Usage

import { route } from 'ziggy-js';

// Simple route with no parameters
route('home'); // 'https://example.com'

// Route with a single parameter
route('posts.show', 1); // 'https://example.com/posts/1'

// Route with multiple parameters
route('posts.comments.show', [1, 2]); 
// 'https://example.com/posts/1/comments/2'

// Route with named parameters
route('posts.show', { post: 1 });
// 'https://example.com/posts/1'

​
Object Parameters

// Pass a model object with id
const post = { id: 42, title: 'Hello World' };
route('posts.show', post); // 'https://example.com/posts/42'

// Custom route key binding
const post = { uuid: 'abc-123', title: 'Hello World' };
route('posts.show', post); // 'https://example.com/posts/abc-123'
// (assumes route has bindings configured: { post: 'uuid' })

​
Query Parameters

// Add query string parameters using _query
route('posts.index', { _query: { page: 2, sort: 'recent' } });
// 'https://example.com/posts?page=2&sort=recent'

// Combine route and query parameters
route('posts.show', { post: 1, _query: { lang: 'en' } });
// 'https://example.com/posts/1?lang=en'

​
Relative URLs

// Generate relative paths instead of absolute URLs
route('posts.show', 1, false); // '/posts/1'

route('posts.index', null, false); // '/posts'

​
Custom Configuration

// Provide a custom Ziggy config
const customConfig = {
  url: 'https://api.example.com',
  port: null,
  defaults: {},
  routes: {
    'api.posts.index': {
      uri: 'api/posts',
      methods: ['GET', 'HEAD']
    }
  }
};

route('api.posts.index', null, true, customConfig);
// 'https://api.example.com/api/posts'

​
Getting a Router Instance

// Call without arguments to get a Router instance
const router = route();

// Use Router methods
router.current(); // 'posts.show'
router.has('posts.index'); // true
router.params; // { post: '1', lang: 'en' }

​
Error Handling

The route() function throws errors in the following cases: 
// Route doesn't exist
try {
  route('nonexistent.route');
} catch (error) {
  // Error: Ziggy error: route 'nonexistent.route' is not in the route list.
}

// Missing required parameter
try {
  route('posts.show'); // route requires {post} parameter
} catch (error) {
  // Error: Ziggy error: 'post' parameter is required for route 'posts.show'.
}

// Parameter doesn't match where constraint
try {
  route('posts.show', 'invalid'); // route has where('post', '[0-9]+')
} catch (error) {
  // Error: Ziggy error: 'post' parameter 'invalid' does not match required format '[0-9]+' for route 'posts.show'.
}

// Missing route model binding key
try {
  const post = { title: 'Hello' }; // missing 'id' or custom binding key
  route('posts.show', post);
} catch (error) {
  // Error: Ziggy error: object passed as 'post' parameter is missing route model binding key 'id'.
}

​
TypeScript Support

Ziggy provides full TypeScript support with autocomplete for route names and type-checked parameters: 
import { route } from 'ziggy-js';

// Autocomplete for route names
route('posts.show', 1); // ✓ TypeScript knows this route exists

// Type-checked parameters
route('posts.show', { post: 1 }); // ✓
route('posts.show', { invalid: 1 }); // ✗ Type error

// Return type is branded RouteUrl string
const url: RouteUrl = route('posts.index'); // ✓
Generate TypeScript definitions with: 
php artisan ziggy:generate --types

​
Implementation Details

The route() function is a lightweight wrapper around the Router class: 
export function route(name, params, absolute, config) {
    const router = new Router(name, params, absolute, config);
    return name ? router.toString() : router;
}
When called with a route name, it:
  1. Creates a new Router instance
  2. Parses and normalizes the parameters
  3. Compiles the route template with the parameters
  4. Returns the generated URL string
When called without a name, it returns the Router instance directly for use with methods like current(), has(), and accessing the params property.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us