From 0bb18ad79dd074d124f33d9a700d2b8f4a4d0cc0 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 25 Feb 2021 17:48:31 +0100
Subject: [PATCH] docs: document optional external route refs

---
 docs/plugins/composability.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md
index 6106fa9141..07a2b503ec 100644
--- a/docs/plugins/composability.md
+++ b/docs/plugins/composability.md
@@ -305,6 +305,37 @@ in a different file than the one that creates the plugin instance, for example a
 top-level `routes.ts`. This is to avoid circular imports when you use the route
 references from other parts of the same plugin.
 
+### Optional External Routes
+
+When creating an `ExternalRouteRef` it is possible to mark it as optional:
+
+```ts
+const headerLinkRouteRef = createExternalRouteRef({
+  id: 'header-link',
+  optional: true,
+});
+```
+
+An external route that is marked as optional is not required to be bound in the
+app, allowing it to be used as a switch for whether a particular link should be
+displayed or action should be taken.
+
+When calling `useRouteRef` with an optional external route, its return signature
+is change to `RouteFunc | undefined`, allowing for logic like this:
+
+```tsx
+const MyComponent = () => {
+  const headerLink = useRouteRef(headerLinkRouteRef);
+
+  return (
+    <header>
+      My Header
+      {headerLink && <a href={headerLink()}>External Link</a>}
+    </header>
+  );
+};
+```
+
 ### Parameterized Routes
 
 A new addition to `RouteRef`s is the possibility of adding named and typed