# Route Handler Modules

After a router confirms that an incoming location change matches a route definition, what happens next?

The router accesses `RouteDefinition.handler` to determine the associated **view**, or the component that displays when the application navigates to a location. A `RouteHandler` module uses its `update()` function to provide the router with the right view to display.

Let's break down this process in detail.

:::note
Route handler **modules**, which are used in client-side routing, aren’t the same as [route handler **functions**](/docs/platform/lwr/guide/lwr-routing-server.md#route-handler-functions), which are used in server-side routing.
:::

## Call RouteDefinition.handler

After a router validates an incoming location change, it accesses the `handler` property of the corresponding route definition to determine the new view.

[`RouteDefinition.handler`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.md) contains a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) for the `RouteHandler` module. In LWR, route handler modules are always provided via promises. Promises allow the module code to be lazily loaded, which improves application performance.

## Create RouteHandler module

Then, the router uses the `new()` method to create a RouteHandler module. The route handler is active upon construction, and it can immediately pass results to the callback via the `update()` method.

### new()

[`new()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/new.md) takes a reference to a route handler callback (`RouteHandlerCallback`).

```sfdocs-code {"lang":"javascript", "title": "new()", "src": "" }
public void new(callback: RouteHandlerCallback)
```

### RouteHandlerCallback and RouteDestination

`RouteHandlerCallback` contains a route destination object ([`RouteDestination`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.md)). `RouteDestination` contains a [`ViewSet`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.md#viewset) object that specifies the view to display.

```sfdocs-code {"lang":"javascript", "title": "RouteHandlerCallback", "src": "" }
type RouteHandlerCallback = (routeDestination: RouteDestination) => void;
```

![Diagram showing input and output for new().](https://a.sfdcstatic.com/developer-website/sfdocs/lwr-node/media/method-new.png)

It's important to maintain a reference to the callback in the RouteHandler module, like this:

```sfdocs-code {"lang":"javascript", "title": "RouteHandler module", "src": "" }
export default class RecipeHandler {
    callback: RouteHandlerCallback;   // Callback for the route handler module RecipeHandler

    constructor(callback: RouteHandlerCallback) {
        this.callback = callback;     // Important: maintain a reference to the callback
    }
}
```

## Pass RouteInstance to RouteHandler.update()

Finally, `RouteHandler.update()` takes `RouteInstance` and returns view component information via a callback from the `update` function. This changes what the user sees in the browser.

[`RouteInstance`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routeinstance.md) contains information about a location ([`PageReference`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/pagereference.md)). It tells the route handler which view to show the user.

```sfdocs-code {"lang":"javascript", "title": "RouteInstance", "src": "" }
interface RouteInstance {
    // location information passed to `RouteHandler.update()`
    id: string; // RouteDefinition.id
    attributes: { [key: string]: string | null };
    state: { [key: string]: string | null };
    pageReference: PageReference;
}
```

### update()

The [`update()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/update.md) method accepts a `RouteInstance` object.

`update()` invokes the `RouteHandlerCallback` from `RouteHandler.new` to return the `ViewSet` that corresponds to the callback's `RouteDestination`.

![Diagram showing input and output for update().](https://a.sfdcstatic.com/developer-website/sfdocs/lwr-node/media/method-update.png)

## RouteHandler Example

`recipeHandler` below is an example of a `RouteHandler` module.

```sfdocs-code {"lang":"typescript", "title": "my/recipeHandler RouteHandler module", "src": "" }
import type { Module, RouteHandlerCallback } from "lwr/router";

export default class RecipeHandler {
  callback: RouteHandlerCallback;

  // Create new RouteHandler module via callback
  constructor(callback: RouteHandlerCallback) {
    this.callback = callback; // Important: maintain a reference to the callback
  }

  // Implementation of dispose()
  dispose(): void {
    // perform cleanup tasks
  }

  // Implementation of update()
  update(routeInfo: RouteInstance): void {
    // called every time a RouteDefinition with this handler matches a location during processing
    const {
      attributes: { cat }, // location information
    } = routeInfo;
    const category = cat || "entree"; // cat may be null
    const viewSpecifier = `my/${category}Recipe`; // e.g. "my/dessertRecipe"
    this.callback({
      viewset: {
        // return view component info based on the recipe's category
        default: {
          module: (): Promise<Module> => import(viewSpecifier),
          specifier: viewSpecifier,
        },
      },
    });
  }
}
```

[Simple Client-Side Routing](/docs/platform/lwr/guide/lwr-routing-example-simple.md) includes examples of additional route definition handlers, including for branching logic.

### dispose()

[`RouteHandler.dispose`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/dispose.md) is called when a route handler is no longer needed by the app and no longer emits view changes. A disposed route handler can't be used again.

## Next Steps

To use a router in your app, you have to attach it to the DOM with a router container. To learn how, check out [Router Containers](/docs/platform/lwr/guide/lwr-router-containers.md).