docs: add README example

Author: adamstankiewicz

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>
+```

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,