Routing
Connect your view to other views and tasks
Navigation
Navigation
The simplest way to create a link from your view to a task or another view is to use the
href
property on a Button
or Link
.The
href
can navigate to a task by using the syntax href={{ task: my_task }}
or to a view by
using the syntax href={{ view: my_view }}
.You can also add parameters to the task or view by including the
params
field. For example, if you
have a task that takes a name
parameter, you can set the params field to { name: "Sarah" }
and
the task will be opened with name
pre-filled to "Sarah".tsxCopied1<Button href={{ task: "my_task" }}>Navigate to my_task</Button>2<Button href={{ task: "my_task", params: { name: "Sarah" } }}>3Navigate to my_task with parameters4</Button>5<Link href={{ task: "my_task" }}>Navigate to my_task</Link>
tsxCopied1<Button href={{ view: "my_view" }}>Navigate to my_view</Button>2<Button href={{ view: "my_view", params: { name: "Sarah" } }}>3Navigate to my_view with parameters4</Button>5<Link href={{ view: "my_view" }}>Navigate to my_view</Link>
View parameters
View parameters
View parameters are inputs to a view that allow users to pass in data to the view. View parameters
are passed to a view as a prop called
params
in the top-level View component.tsxCopied1import { Text } from "@airplane/views";2import airplane from "airplane";34const MyView = ({ params }) => {5return <Text>Hello {params.name}</Text>;6};78export default airplane.view({ slug: "my_view" }, MyView);
The parameter state is encoded in the URL as query parameters so that users can easily share links
to views with input data.
View parameters are useful since they allow you to share views in certain states. For example, say
we have a View with a form. We want to share this view with a link that has the form pre-filled. We
can do this by adding parameters to the view that represents the form data.
tsxCopied1import { Form, TextInput } from "@airplane/views";2import airplane from "airplane";34const CatForm = ({ params }) => {5const { name, breed = "Domestic short hair" } = params;6return (7<Form>8<TextInput id="name" label="Name" defaultValue={name} />9<TextInput id="breed" label="Breed" defaultValue={breed} />10</Form>11);12};1314export default airplane.view({ slug: "cat_form" }, CatForm);
We can then use
https://app.airplane.dev/views/vew123?name=Felix
to link to the form with the name
set to "Felix" and breed set to the default breed "Domestic short hair".We can also link to this view with parameters from a view by using the routing technique described
in Navigation.
Peek
Peek
Another way to link to an entity is through a peek. A peek is a way to open a task or view without
leaving the current view. By default, peeks will open a preview of the entity on the right side of
the Page. You can set the
as
field to center_peek
to open it in a modal.You can open a task, view, runbook, or page peek by calling
router.peek
. The peek
function takes
an object with a task
, view
, runbook
, page
, or href
field representing the slug of the
task, view, or runbook or the path of the page or the url to preview.tsxCopied1import { useRouter } from "@airplane/views";23const FeatureFlagDashboard = () => {4const router = useRouter();5return (6{/* ... */}7<Button onClick={() => router.peek({ task: "create_feature" })}>Create feature</Button>8{/* ... */}9);10};
You can also pass Task params, Runbook params, or
Views params to the peek by including a
params
field in the peek argument.
This will pre-fill the parameters in the task/runbook/view when the preview is opened.tsxCopied1<Button onClick={() => router.peek({ task: "create_feature", params: { name: "Delete user" } })}>2Create feature3</Button>
You can specify whether to open the peek as a modal or a side peek by including an
as
field, which
can either be side_peek
or center_peek
. The default is to open in a side peek.tsxCopied1<Button2onClick={() =>3router.peek({ task: "create_feature", params: { name: "Delete user" }, as: "center_peek" })4}5>6Create feature7</Button>
Router
Router
The
useRouter
hook provides access to the router. The router contains low-level methods for
linking and navigating between your view and other views and tasks. These functions can be used when
you want finer control over your view's routing behavior.For example, you may want to programmatically navigate to a view or task in your custom component,
which you can accomplish by using
router.navigate
.tsxCopied1const router = useRouter();2return (3<button4onClick={() => {5router.navigate({ task: "my_task" });6}}7>8Navigate to my_task9</button>10);
Or, you may want to programmatically open a view or task in a new tab, which you accomplish do by
using
router.getHref
.tsxCopied1const router = useRouter();2return (3<button4onClick={async () => {5const href = await router.getHref({ task: "my_task" });6window.open(href, "_blank");7}}8>9Open my_task in a new tab10</button>11);
API reference
API reference
tsxCopied1const { params, navigate, getHref, peek } = useRouter();
Returns
Returns
params
The parameters passed to this view.
navigate
Navigate to a task or view.
NavigateParams
is either:{ task: string, params?: Params }
to navigate to a task{ view: string, params?: Params }
to navigate to another view{ params?: Params }
to navigate to the current view
getHref
Get a href string that navigates to a task or view.
GetHrefParams
is either:{ task: string, params?: Params }
to get a href for a task{ view: string, params?: Params }
to get a href for a view{ params?: Params }
to get a href for the current view
peek
Open a peek to a task or view.
PeekParams
is either:{ task: string, params?: Params }
to peek at a task{ view: string, params?: Params }
to peek at a view