Link
The Link component returns a Theme-ui Link component for external links or a Theme-ui Link component cast as a Gatsby Link component (using the Theme-ui as prop) for internal links.
This ensures that internal links are processed by Gatsby Link (required by Gatsby) but are Theme-ui aware (recognize Link variants and the sx prop, etc...)
For some external links, an icon and extra styles are applied (email, tel, etc,...)
In markdown documents a tags are replaced by the Link component with variant="mdx".
Link @"src/components/Link"
Edit the props to see this component update live!
Important!
Use the `href` prop. The Link component from this theme uses the `href` prop (as does the Theme-UI Link component,) and not the `to` prop used by Gatsby Link
Internal Links in markdown
The same styles should be applied to links regardless of whether a writer uses markdown link syntax an a tag or the Link component when writing markdown.
[Documentation: Link](/documentation/link/)
<a href="/documentation/link/">Documentation: Link</a>
<Link href="/documentation/link/">Documentation: Link</Link>
External links in markdown
The same styles should be applied to links regardless of whether a writer uses markdown link syntax an a tag or the Link component when writing markdown.
Standard links
[Google](https://www.google.com)
<a href="https://www.google.com">Google</a>
<Link href="https://www.google.com">Google</Link>
Using the Link component from Gatsby (aliased as GatsbyLink) or the Link component from Theme-UI (aliased as ThemeUILink) doesn't get the proper styling which includes the external link icon.
<GatsbyLink href="https://www.google.com">Google</GatsbyLink>
<ThemeUILink href="https://www.google.com">Google</ThemeUILink>
External links with dedicated styles
Some external links receive dedicated styling...
Phone:
[call now!](tel:+12065550100)
Email:
[email us!](mailto:someone@example.com)
Example: links inline with text
Link text should align with the paragraph baseline and icons should be aligned vertically in the center of the link text.
Nisi fugiat amet qui anim cillum id consequat occaecat external link minim mollit amet occaecat dolore irure anim cillum tempor et qui fugiat esset veniam amet esse dolore ex. Irure sint. Minim mollit amet occaecat dolore internal link irure anim cillum tempor et qui fugiat esset veniam amet esse dolore ex. Laboris enim officia exercitation call now! proident irure sint. Minim mollit amet occaecat dolore irure anim cillum tempor et qui fugiat esset veniam email us! amet esse dolore ex. Laboris enim officia exercitation proident irure sint.
Variants
Variants add color and hover styles to links. Pair a Link variant with a containing element with background set to the same color for sympathetic color matching.
The mdx variant is applied to links in markdown.
The ui variant is intended for use in menus, navigation, or link components styled as buttons. The chrome variant is is intended for use in menus, navigation, or link components styled as buttons, against a chrome background.
Internal Links:
Variant: mdx
Variant: ui
Variant: chrome
Variant: primary
Variant: secondary
Variant: black
Variant: grey
Variant: white
Variant: info
Variant: success
Variant: warning
Variant: error
Variant: fancy
External Links:
Variant: mdx
Variant: ui
Variant: chrome
Variant: primary
Variant: secondary
Variant: black
Variant: grey
Variant: white
Variant: info
Variant: success
Variant: warning
Variant: error
Variant: fancy
Props
noExternalLinkIcon
The noExternalLinkIcon prop removes the external link icon.
Example
<Link href="//google.com" noExternalLinkIcon></Link>
partiallyActive
The partiallyActive prop will be passed through to the Theme-UI Link component cast as a Gatsby Link component is that behavior is required for internal links.
Using icons in links
Icon components or SVG components should be wrapped in a Box component with variant="layout.svg". This applies styling to ensure the icon aligns with the baseline of the label for icons placed to left or the right of the label
Example
<Box sx={{ display: "flex", gap: 3 }}><Link variant="fancy" href="https://www.github.com" noExternalLinkIcon>Get the code!<Box as="span" variant="layout.svg"><GrGithub /></Box></Link><Link variant="fancy" href="https://www.github.com" noExternalLinkIcon><Box as="span" variant="layout.svg"><GrGithub /></Box>Get the code!</Link></Box>
Links with left and right icons inline with text:
Example: inline links with icons
<Text>Nisi fugiat occaecat<Link variant="mdx" href="https://www.github.com" noExternalLinkIcon mr={1}>Get the code!<Box as="span" variant="layout.svg"><GrGithub /></Box></Link>minim mollit occaecat dolore<Link variant="mdx" href="https://www.github.com" noExternalLinkIcon mr={1}><Box as="span" variant="layout.svg"><GrGithub /></Box>Get the code!</Link>laboris enim officia exercitation proident irure sint.</Text>
Theme
json{"mdx": {"variant": "text.paragraph.default","padding": 0,"margin": 0,"color": "primary","textDecoration": "underline","transition": "ease color 250ms","&:hover": {"color": "primaryMuted"}},"ui": {"margin": 0,"cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","textDecoration": "none","transition": "ease color 250ms","color": "uiText","&:hover": {"color": "uiTextHover","textDecoration": "none"}},"chrome": {"margin": 0,"cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","textDecoration": "none","transition": "ease color 250ms","padding": 0,"color": "chromeText","&:hover": {"color": "chromeTextHover"}},"primary": {"variant": "text.paragraph.default","padding": 0,"margin": 0,"textDecoration": "none","cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","transition": "ease color 250ms","color": "primaryText","&:hover": {"color": "primaryTextHover","textDecoration": "none"}},"secondary": {"variant": "text.paragraph.default","padding": 0,"margin": 0,"textDecoration": "none","cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","transition": "ease color 250ms","color": "secondaryText","&:hover": {"color": "secondaryTextHover","textDecoration": "none"}},"black": {"variant": "text.paragraph.default","padding": 0,"margin": 0,"textDecoration": "none","cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","transition": "ease color 250ms","color": "blackText","&:hover": {"color": "blackTextHover","textDecoration": "none"}},"grey": {"variant": "text.paragraph.default","padding": 0,"margin": 0,"textDecoration": "none","cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","transition": "ease color 250ms","color": "greyText","&:hover": {"color": "greyTextHover","textDecoration": "none"}},"white": {"variant": "text.paragraph.default","padding": 0,"margin": 0,"textDecoration": "none","cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","transition": "ease color 250ms","color": "whiteText","&:hover": {"color": "whiteTextHover","textDecoration": "none"}},"info": {"variant": "text.paragraph.default","padding": 0,"margin": 0,"textDecoration": "none","cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","transition": "ease color 250ms","color": "infoText","&:hover": {"color": "infoTextHover","textDecoration": "none"}},"success": {"variant": "text.paragraph.default","padding": 0,"margin": 0,"textDecoration": "none","cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","transition": "ease color 250ms","color": "successText","&:hover": {"color": "successTextHover","textDecoration": "none"}},"warning": {"variant": "text.paragraph.default","padding": 0,"margin": 0,"textDecoration": "none","cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","transition": "ease color 250ms","color": "warningText","&:hover": {"color": "warningTextHover","textDecoration": "none"}},"error": {"variant": "text.paragraph.default","padding": 0,"margin": 0,"textDecoration": "none","cursor": "pointer","fontFamily": "sans","fontWeight": "light","fontSize": "inherit","transition": "ease color 250ms","color": "errorText","&:hover": {"color": "errorTextHover","textDecoration": "none"}},"fancy": {"color": "white","backgroundColor": "chrome","border": "1px solid","borderColor": "chrome","borderRadius": "md","px": 2,"py": 1,"fontFamily": "sans","fontWeight": "light","fontSize": "inherit","lineHeight": "normal","textDecoration": "none","display": "flex","gap": 1,"alignItems": "center","&:hover": {"color": "chrome","backgroundColor": "#ffffff","backgroundImage": "none","border": "1px solid","borderColor": "chrome"}}}