Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tighten/ziggy/llms.txt

Use this file to discover all available pages before exploring further.

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