# Utilities
Utilities are simple tools with their own views, routes, navigation items, and permissions.
## What's a utility?
A utility is really just a route or two with a view, injected into the _Utilities_ area of the control panel,
and wrapped up with a permission. You _could_ make the same thing by wiring up the individual parts, but creating
a utility is a shortcut.
To get an idea for what a utility is, take a look at the utilities Statamic ships with:
- A page for viewing cache information and a button to clear it.
- A page to list PHP settings from `phpinfo()`.
- A page letting you clear search indexes.
- A page to view email configuration and send a test.
## Creating a utility
Registering a utility will give you a route, nav item, and a permission for free.
In a service provider's `boot` method, you can register a utility with the `Utility` facade.
Start with `Utility::register()` with the handle of the utility, then chain as many methods as you want.
Make sure to surround any utility registrations in a `Utility::extend` closure.
``` php
use Statamic\Facades\Utility;
public function boot()
{
Utility::extend(function () {
Utility::register('data_wangjangler')
->inertia('my-addon::DataWangjangler', fn ($request) => [
'items' => Item::all(),
]);
});
}
```
The first argument is the name of [an Inertia page component](/control-panel/css-javascript.md#inertia), and the second is an optional closure that returns props for the component.
You'll need to register the Inertia page using `Statamic.$inertia.register()`:
``` js
import DataWangjangler from './components/DataWangjangler.vue';
Statamic.booting(() => {
Statamic.$inertia.register('my-addon::DataWangjangler', DataWangjangler);
});
```
Then create your Vue component:
``` vue
Wangjangle that data
{{ item.name }}
```
:::tip
For help setting up Vite and Vue in your project, please see the [Vite Tooling](/addons/vite-tooling.md) (for addons) or [CSS & JavaScript](/control-panel/css-javascript.md#inertia) guides.
:::
## Customizing the navigation and card
You can customize the nav item, description, icon, and other details on the index listing by chaining the corresponding methods.
The `icon()` method accepts the name of an [icon included in Statamic](https://ui.statamic.dev/?path=/docs/components-icon--docs#available-icons), or an SVG string containing a custom icon (be sure to use `fill="currentColor"`):
``` php
use Statamic\Facades\Utility;
public function boot()
{
Utility::extend(function () {
Utility::register('data_wangjangler')
->inertia('my-addon::DataWangjangler')
->title('Data Wangjangler')
->navTitle('Wangjangler')
// Icon included in Statamic
->icon('share-mega-phone')
// Custom icon
->icon('')
->description('Wanjangles your data at the click of a button.')
->docsUrl('https://yoursite.com/docs/wangjangler');
});
}
```
## Using a custom controller
Instead of passing data to the utility in your service provider, you may define a custom controller instead.
``` php
Utility::register('data_wangjangler')
->action(WangjanglerController::class) // call the __invoke method
->action([WangjanglerController::class, 'index']); // call the index method
```
In your controller, you can do whatever you need to do, then return an Inertia.js Vue component:
``` php
use Inertia\Inertia;
class WangjanglerController
{
public function __invoke()
{
$items = Item::all();
return Inertia::render('my-addon::DataWangjangler', [
'items' => $items,
]);
}
}
```
Data will be passed to the component as props:
```vue
```
## Routing
A route will be created for you automatically, using the slugified version of the handle you initially provided. eg. `/cp/utilities/data-wangjangler`
If your utility needs to _do_ something (like how you click a button in the cache manager utility to actually clear the cache), you may register additional routes.
``` php
Utility::register('data_wangjangler')->routes(function ($router) {
$router->post('/', [WangjanglerController::class, 'process'])->name('process');
});
```
``` php
// WangjanglerController.php
public function process(Request $request)
{
// Do the processing...
return redirect()->back()->with('success', 'Data has been wangjangled!');
}
```
You can use the `cp_route` helper in PHP to generate URLs to your utility routes:
``` php
cp_route('utilities.data-wangjangler') // /cp/utilities/data-wangjangler
cp_route('utilities.data-wangjangler.process') // /cp/utilities/data-wangjangler/process
```
## Permissions
A single permission will be registered automatically using the handle.
eg. `access data_wangjangler utility`
Users without this permission will not see the utility in the navigation or utility listing.
## Using Blade
For simpler utilities, or if you prefer not to use Vue, you may build utilities using Blade, but there's a few limitations to be aware of:
- Blade-rendered pages trigger a full page reload rather than the SPA-style transitions used elsewhere in the Control Panel.
- Under the hood, Blade views are rendered inside a Vue component, which means `