From fa72a7df62bf515287382bd50dc5230aa2448ba7 Mon Sep 17 00:00:00 2001
From: Adam Stankiewicz <agstanki@gmail.com>
Date: Wed, 29 May 2024 12:22:00 -0400
Subject: [PATCH] docs: add README example

---
 src/Hyperlink/README.md | 17 ++++++++++++++++-
 src/Hyperlink/index.tsx |  2 ++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/Hyperlink/README.md b/src/Hyperlink/README.md
index d3ef064f1e..0f41cbba95 100644
--- a/src/Hyperlink/README.md
+++ b/src/Hyperlink/README.md
@@ -7,7 +7,7 @@ categories:
 - Buttonlike
 status: 'Needs Work'
 designStatus: 'Done'
-devStatus: 'To Do'
+devStatus: 'Done'
 notes: |
   Improve prop naming. Deprecate content prop.
   Use React.forwardRef for ref forwarding.
@@ -100,3 +100,18 @@ notes: |
   </div>
 </div>
 ```
+
+## with custom link element
+
+``Hyperlink`` typically relies on the standard HTML anchor tag (i.e., ``a``); however, this behavior may be overriden when the destination link is to an internal route where it should be using routing instead (e.g., ``Link`` from React Router).
+
+```jsx live
+<Hyperlink
+  as={GatsbyLink}
+  // `destination` is still a required prop even though the `to` takes precedence.
+  destination="/components/button"
+  to="/components/button"
+>
+  Button
+</Hyperlink>
+```
\ No newline at end of file
diff --git a/src/Hyperlink/index.tsx b/src/Hyperlink/index.tsx
index 5928fab105..f5477f1ed8 100644
--- a/src/Hyperlink/index.tsx
+++ b/src/Hyperlink/index.tsx
@@ -1,5 +1,6 @@
 import React from 'react';
 import PropTypes from 'prop-types';
+import isRequiredIf from 'react-proptype-conditional-require';
 import classNames from 'classnames';
 import {
   type BsPrefixRefForwardingComponent as ComponentWithAsProp,
@@ -119,6 +120,7 @@ Hyperlink.defaultProps = {
 };
 
 Hyperlink.propTypes = {
+  /** specifies the component element type to render for the hyperlink */
   as: PropTypes.elementType,
   /** specifies the URL */
   destination: PropTypes.string.isRequired,