Some props/prop values deprecated in SWAN v3.3
Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.
Link
Hyperlinked text for navigating to a new page.
Use Link...
- To navigate the user to a new page.
- To navigate the user to a different section of the same page.
- To change the URL.
- To cause a browser redraw/refresh.
- To download a linked resource.
Don't use Link...
- To perform actions other than navigation; use Button for this instead. This includes:
- to trigger an action in the system
- to prompt the user to perform an action
- to confirm an action
- to draw attention to important actions
- To provide same-page navigation that requires a persistent navigation element as the user scrolls. Use Anchor Bar instead.
Width
Use width="full-width" to make the link fill its container instead of being inline.
Skins
CTA
Use as a call-to-action in Standard Tile or Banner.
Use skin="cta" to position the arrow to the right of the text.
Use skin="cta-left" to position the arrow to the left.
Inside a block of Typography that sets the text
color to white, the CTA link automatically changes its icon to white
Unstyled
- This variant removes the normal link styling, such as color and underline.
- Only use it with something that provides its own affordance (that is, something that shows a hover and active state). Otherwise, users won’t have a way to know it’s clickable.
- A link with the
unstyledskin won't show up with normal link styling, although it still gets the "pointer" cursor on hover.
Covering
Use covering to increase the clickable target of a Link to cover the nearest ancestor element that has positioning context. This is usually a Standard Tile or a Card with skin="link".
Only wrap the Link around the content that should be included in the accessible name, which is usually the title or call-to-action.
Use skin="unstyled" to remove the normal link styling.
With icon
withIconSeparated is deprecated in SWAN v3.3
Replace it with withIcon which behaves the same.
- The "link with icon" feature is a link that has both text and an image or icon, and vertically centers both sub-elements.
- "Link with icon" can contain any type of image or icon.
- "CTA link" uses specific text styling and only uses the Arrow icon.
As a Button
Use render for Links with the behavior of a Button. Refer to render guidelines.
Links that perform an action on the current page should render a <button> instead of an <a> for accessibility requirements.
Button as a Link
Use render for Buttons with the behavior of a Link. Refer to render prop guidelines.
Buttons that take users to a new page should render an <a> instead of a <button> for accessibility requirements.
Global Link Component
Some routing frameworks, like Gatsby, Next, or TanStack Router, suggest using their own Link component for routing. While that can be done at the component level using the as or render props, it can also be configured within SwanProvider. For more information, see the SwanProvider setup docs.
Best practices
Link types
Internal links
- For text that takes users to another page, or a different section of the same page.
- Use Anchor Bar to provide same page navigation that requires a persistent navigation element as the user scrolls.
Outbound links
For taking the user to another site.
CTA links
For use as a call-to-action in Standard Tile, Secondary Tile, or Standard Hero.
A list of links
Typically placed in the Navigation menu, a lateral menu, or the Footer of the page.
Unstyled links
For use in components that already provide their own affordance and hover styling, such as Standard Tile. Unstyled links provide no affordance.
Appearance
Avoid changing the styling and type size for links.
Placement
- Use links in body copy and legal copy.
- CTA links can be placed as a call-to-action in Standard Tile, Secondary Tile, or Banner.
Content
- Explanatory
- Link text should make sense on its own ("click here" doesn’t indicate where you’ll be taken).
- Help users predict where a link will lead before they click it.
- Concise
- Keep the link copy clear and simple—two or three words are recommended. The fewer words, the better, to avoid text wrapping.
- Purposeful
- The link text alone should convey the function of the link.
- Use language that leads users to the next step.
- Accessible & Inclusive
- Link text should also be unique and easy to read out loud.
- Avoid using words that aren't inclusive in your writing, such as "see" or "view."
- Try "show", "explore", or "browse" instead.
- Describe the page people will be taken to in the hyperlink.
- DO: Learn more about our Satisfaction Guarantee
- DON'T: Learn more about our Satisfaction Guarantee here
SEO considerations
- Any link to another internal page must be part of the page's source HTML (not dynamically added via JavaScript) for search engines to index it.
- Add the
rel="nofollow"attribute to internal links that are pointing to a page that should not be crawled by search engine bots.
Accessibility
Avoid using the unstyled skin unless there is something else providing visual affordance (not just on hover, since not all users are mouse users).
Props
Link
This component is implemented using the
<a /> as the root element. You can utilize the native attributes supported by <a /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.See core props for additional props that can be applied to this component.
| prop | type | required | description | default |
|---|---|---|---|---|
| width | "standard" | "full-width" | null | false | Set the width of the Link.
One of: "standard", "full-width". | standard |
| to | string | null | false | Sets the destination URL in case you are setting globalLinkComponent(SwanProvider) to 3rd party library's Link (Gatsby, Next.js, React router, etc.). | null |
| skin | "standard" | "unstyled" | "cta" | "cta-left" | null | false | The visual style of the Link.
One of: "standard", "cta", "cta-left", "unstyled". | standard |
| covering | boolean | null | false | Whether the Link's clickable target should cover the entirety of it's nearest ancestor element. | null |
| withIcon | boolean | null | false | Whether this is a "link with icon". | null |
| withIconSeparated | boolean | null | false | ⚠️ Deprecated - `withIconSeparated` behaves the same as `withIcon`, use `withIcon` instead. @description Whether this "link with icon" has the icon and text visually separated. | null |
Related
How does Link meet your needs?
