From a37ad0ae077cf8892a25bb83f42a73ea51da10f0 Mon Sep 17 00:00:00 2001
From: Matt Carlotta <carlotta.matt@gmail.com>
Date: Wed, 1 Apr 2020 03:21:04 -0700
Subject: [PATCH] Add notes to styled-components example README (#11540)

* Add notes to styled-components example README

* Adjust notes to styled-components example README
---
 examples/with-styled-components/README.md | 53 +++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/examples/with-styled-components/README.md b/examples/with-styled-components/README.md
index 78fecbf2cadd1..8575665ecdb1d 100644
--- a/examples/with-styled-components/README.md
+++ b/examples/with-styled-components/README.md
@@ -46,3 +46,56 @@ Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm
 ### Try it on CodeSandbox
 
 [Open this example on CodeSandbox](https://codesandbox.io/s/github/zeit/next.js/tree/canary/examples/with-styled-components)
+
+### Notes
+
+When wrapping a [Link](https://nextjs.org/docs/api-reference/next/link) from `next/link` within a styled-component, the [as](https://styled-components.com/docs/api#as-polymorphic-prop) prop provided by `styled` will collide with the Link's `as` prop and cause styled-components to throw an `Invalid tag` error. To avoid this, you can either use the recommended [forwardAs](https://styled-components.com/docs/api#forwardedas-prop) prop from styled-components or use a different named prop to pass to a `styled` Link.
+
+<details>
+<summary>Click to expand workaround example</summary>
+<br />
+
+**components/StyledLink.js**
+
+```javascript
+import React from 'react'
+import Link from 'next/link'
+import styled from 'styled-components'
+
+const StyledLink = ({ className, children, href, forwardAs }) => (
+  <Link href={href} as={forwardAs} passHref>
+    <a className={className}>{children}</a>
+  </Link>
+)
+
+export default styled(StyledLink)`
+  color: #0075e0;
+  text-decoration: none;
+  transition: all 0.2s ease-in-out;
+
+  &:hover {
+    color: #40a9ff;
+  }
+
+  &:focus {
+    color: #40a9ff;
+    outline: none;
+    border: 0;
+  }
+`
+```
+
+**pages/index.js**
+
+```javascript
+import React from 'react'
+import StyledLink from '../components/StyledLink'
+
+export default () => (
+  <StyledLink href="/post/[pid]" forwardAs="/post/abc">
+    First post
+  </StyledLink>
+)
+```
+
+</details>