diff --git a/UNRELEASED.md b/UNRELEASED.md
index b236ac01deb..a1eef365dcf 100644
--- a/UNRELEASED.md
+++ b/UNRELEASED.md
@@ -35,6 +35,7 @@ Use [the changelog guidelines](https://git.io/polaris-changelog-guidelines) to f
- Converted `ResourceList`, `ResourcePicker`, and `Select` examples to functional components ([#2133](https://github.com/Shopify/polaris-react/pull/2133))
- Converted `TextField`, `Toast`, and `TopBar` examples to functional components ([#2135](https://github.com/Shopify/polaris-react/pull/2135))
- Updated the `withContext` section in the [v3 to v4 migration guide](https://github.com/Shopify/polaris-react/blob/master/documentation/guides/migrating-from-v3-to-v4.md) ([#2124](https://github.com/Shopify/polaris-react/pull/2124))
+- Clarify when to use the `external` prop on the `Link` component ([#2153](https://github.com/Shopify/polaris-react/pull/2153))
### Development workflow
diff --git a/src/components/Link/Link.tsx b/src/components/Link/Link.tsx
index e49e6f98791..534b84664e5 100644
--- a/src/components/Link/Link.tsx
+++ b/src/components/Link/Link.tsx
@@ -14,9 +14,9 @@ export interface LinkProps {
id?: string;
/** The url to link to */
url?: string;
- /** The content to display inside link */
+ /** The content to display inside the link */
children?: React.ReactNode;
- /** Use for a links that open a different site */
+ /** Makes the link open in a new tab */
external?: boolean;
/** Makes the link color the same as the current text color and adds an underline */
monochrome?: boolean;
diff --git a/src/components/Link/README.md b/src/components/Link/README.md
index 878a40b8bc3..761b2f78e80 100644
--- a/src/components/Link/README.md
+++ b/src/components/Link/README.md
@@ -107,7 +107,7 @@ Monochrome styles will be applied to links rendered within a `Banner`.
### External link
-Use for text links that point to a different website. They will open in a new browser tab or window.
+Use for text links that should open in a new browser tab (or window, depending on the merchant’s browser settings). Use this only when opening a page in the same tab might disrupt the merchant’s workflow.
```jsx
@@ -184,7 +184,7 @@ To provide consistency and clarity:
#### External links
-The `external` prop adds an icon and a notification that the link opens a new window. Use the `external` prop to make the link open in a new window (or tab, depending on the merchant’s browser settings). Open a page in a new window or tab only when opening a page in the same tab might disrupt the merchant’s workflow.
+The `external` prop adds an icon and a notification that the link opens a new tab. Use the `external` prop to make the link open in a new tab (or window, depending on the merchant’s browser settings). Open a page in a new tab only when opening a page in the same tab might disrupt the merchant’s workflow.
### Keyboard support
diff --git a/src/utilities/link/types.ts b/src/utilities/link/types.ts
index b3ed92ef4d1..a397fb4c122 100644
--- a/src/utilities/link/types.ts
+++ b/src/utilities/link/types.ts
@@ -1,13 +1,13 @@
export interface LinkLikeComponentProps
extends React.HTMLProps {
- /** A destination to link to */
+ /** The url to link to */
url: string;
- /** Forces url to open in a new tab */
+ /** The content to display inside the link */
+ children?: React.ReactNode;
+ /** Makes the link open in a new tab */
external?: boolean;
- /** Tells the browser to download the url instead of opening it. Provides a hint for the downloaded filename if it is a string value. */
+ /** Makes the browser download the url instead of opening it. Provides a hint for the downloaded filename if it is a string value. */
download?: string | boolean;
- /** Content to display inside the link */
- children?: React.ReactNode;
[key: string]: any;
}