Using Next/Link with Theme-UI

Gia Thinh Nguyen

Published on August 17, 2021

Theme-UI

Next.js

Theme-UI provides a wide set of primitive components to build reusable UI. This naturally makes it easy to work with a React-based framework like Next.js. In this tutorial, I'll show you how to make use of the next/link component in any Theme-UI project.

Creating a Link Component

Next.js provides native client side routing with its internal file-system based router through it's Link component, which is actually itself a wrapper for an anchor tag. Theme-UI provides its own primitive anchor component named similarly which we will use to interface with our design system while still retaining that SPA feeling.

Initially, Next.js proposes its use case for the Link to be like so:

import Link from "next/link";

function LinkExample() {
  return (
    <Link href="/home">
      <a>Go Home</a>
    </Link>
  );
}

This might feel awkward at first leaving an anchor without an href, but rest assured the folks behind Next.js know what they are up to. Essentially, the wrapping Link injects the routing magic into its child element, which is expected to be an <a/>.

If you are using the recommended eslint-config-next package for linting Next.js, you won't get any linting errors for leaving out the href attribute in an anchor tag. Find out more about this over here.

That being said, let's create our own fully loaded Link component that resonates with Theme-UI, with the following features:

• Opt into using Next/Link for client-side routing transitions.
• Active routing, add some style for links that match the current URL.
• External links, render a regular anchor tag for links outside of our project.
• Button links, render a link that looks like a button.

Without wasting any more time, let's jump into the code starting with the basic Link.

1
// components/Link.tsx
2
import NextLink from "next/link";
3
import { Link as Anchor } from "theme-ui";
4

5
type LinkProps = React.PropsWithChildren<{}> &
6
  React.ComponentProps<typeof Anchor>;
7

8
export function Link({ children, href, ...props }: LinkProps) {
9
  return (
10
    <NextLink href={href}>
11
      <Anchor
12
        color="text"
13
        sx={{
14
          display: "inline-flex",
15
          fontFamily: "body",
16
          color: "text",
17
          textDecoration: "none",
18
          alignItems: "center",
19
          ":hover": {
20
            cursor: "pointer",
21
            textDecoration: "underline",
22
          },
23
        }}
24
        {...props}
25
      >
26
        {children}
27
      </Anchor>
28
    </NextLink>
29
  );
30
}

And that's really it! We only switched out the default <a/> tag with the Theme-UI anchor with a few added styles, of course to trim the code a bit more we can add these styles into our theme.ts file as the default for all anchor tags. This of course requires you to have a theme ready with the ThemeProvider component already into your _app.tsx.

// styles/theme.ts
import type { Theme } from "theme-ui";

export const theme: Theme = {
  /* ...other tokens */
  styles: {
    a: {
      display: "inline-flex",
      fontFamily: "body",
      fontSize: [3, 4],
      color: "text",
      textDecoration: "none",
      alignItems: "center",
      ":hover": {
        cursor: "pointer",
        textDecoration: "underline",
      },
      ":focus-visible": {
        textDecoration: "underline",
      },
    },
  },
};

Making The Active Link

If you've used react-router before, than you might've remembered that it exposes a component called <NavLink/>, which was a variant of it's own Link with the activeClassName prop that gets added when the current URL of the page matches with it's href. We can use that same logic to our custom Link with the useRouter() hook provided by next-router for some conditional styling.

1
import NextLink from "next/link";
2
import { useRouter } from "next/router";
3
import { Link as Anchor } from "theme-ui";
4

5
type LinkProps = React.PropsWithChildren<{}> &
6
  React.ComponentProps<typeof Anchor>;
7

8
export function Link({ children, href, ...props }: LinkProps) {
9
  const router = useRouter();
10
  const isActive = router.asPath === href;
11

12
  return (
13
    <NextLink href={href}>
14
      <Anchor color={isActive ? "primary" : "text"} {...props}>
15
        {children}
16
      </Anchor>
17
    </NextLink>
18
  );
19
}

Making The External Link Variant

Next, we want our component to handle external links, by it's own implementation, next/link expects to receive an internal route. We can handle external routes with some good old regex magic with this addition:

1
import NextLink from "next/link";
2
import { useRouter } from "next/router";
3
import { Link as Anchor } from "theme-ui";
4

5
type LinkProps = React.PropsWithChildren<{}> &
6
  React.ComponentProps<typeof Anchor>;
7

8
export function Link({ children, href, ...props }: LinkProps) {
9
  const router = useRouter();
10
  const isActive = router.asPath === href;
11

12
  if (href.match(/^(https?:)?\/\//)) {
13
    return (
14
      <Anchor href={href} target="_blank" {...props}>
15
        {children}
16
      </Anchor>
17
    );
18
  }
19

20
  return (
21
    <NextLink href={href}>
22
      <Anchor color={isActive ? "primary" : "text"} {...props}>
23
        {children}
24
      </Anchor>
25
    </NextLink>
26
  );
27
}

As an added bonus, let's make this external link more apparent by adding an icon next to the link. I personally prefer using react-icons as my icon library of choice for this. Since Theme-UI doesn't quite expose its sx props so easily to other React components, this usally calls for some JSX pragma, but it's not everyone's cup of tea, so instead we could build our own <Icon/> component.

import { Box } from "theme-ui";

type IconProps = { size?: number } & 
  React.ComponentProps<typeof Box>;

function Icon({ size, ...props }: IconProps) {
  return <Box sx={{ width: size, height: size }} {...props} />;
}

As mentioned before, we will be using the feather icons from react-icons, as they are bundled as ready to use React components. We would want to maybe control the size of icons via a prop and the other utility props for playing with colours, margin and paddings by spreading the props from our Box primitive.

Now you might be thinking, what the heck, this is just a <div/> underneath, how can it possibly render the icons we need? A-ha, this is where the fun truly starts with the as polymorphic prop which was originally inspired by styled-components but made its way to Theme-UI since it was built with emotion (which of course implementated a similar API, isn't that perfect?). This prop will hijack what's being rendered into whatever custom component or HTML tag you pass it, while preserving styles. That being said, let there be icons ✨!

1
import NextLink from "next/link";
2
import { Link as Anchor, Box } from "theme-ui";
3
import { FiExternalLink } from "react-icons/fi";
4

5
type LinkProps = React.PropsWithChildren<{}> &
6
  React.ComponentProps<typeof Anchor>;
7

8
type IconProps = { size?: number } & 
9
  React.ComponentProps<typeof Box>;
10

11
function Icon({ size, ...props }: IconProps) {
12
  return <Box sx={{ width: size, height: size }} {...props} />;
13
}
14

15
export function Link({ children, href, ...props }: LinkProps) {
16
  const router = useRouter();
17
  const isActive = router.asPath === href;
18
  
19
  if (href.match(/^(https?:)?\/\//)) {
20
    return (
21
      <Anchor href={href} color="text" target="_blank" {...props}>
22
        {children}
23
        <Icon as={FiExternalLink} size={16} ml={1} aria-hidden />
24
      </Anchor>
25
    );
26
  }
27

28
  return (
29
    <NextLink href={href}>
30
      <Anchor color={isActive ? "primary" : "text"} {...props}>
31
        {children}
32
      </Anchor>
33
    </NextLink>
34
  );
35
}

Making The Button Variant

This one pretty much comes as a freebie. Utilizing the as prop seen previously, we can do the same here and render our link component as a button. If we don't want to abstract the button styles into the component itself through some kind of variant prop (not recommended since the API already offers variants) , we can instead make it a sub-component via JSX dot notation. This pattern is particularly useful to keep imports leaner and extending functionality to components. At this point, with this last feature, the final code should look like this:

1
import NextLink from "next/link";
2
import { useRouter } from "next/router";
3
import { Link as Anchor, Box, Button } from "theme-ui";
4
import { FiExternalLink } from "react-icons/fi";
5

6
type LinkProps = React.PropsWithChildren<{}> &
7
  React.ComponentProps<typeof Anchor>;
8

9
type IconProps = { size?: number } & 
10
  React.ComponentProps<typeof Box>;
11

12
function Icon({ size, ...props }: IconProps) {
13
  return <Box sx={{ width: size, height: size }} {...props} />;
14
}
15

16
export function Link({ children, href, ...props }: LinkProps) {
17
  const router = useRouter();
18
  const isActive = router.asPath === href;
19
  
20
  if (href.match(/^(https?:)?\/\//)) {
21
    return (
22
      <Anchor href={href} color="text" target="_blank" {...props}>
23
        {children}
24
        <Icon as={FiExternalLink} size={16} ml={1} aria-hidden />
25
      </Anchor>
26
    );
27
  }
28

29
  return (
30
    <NextLink href={href}>
31
      <Anchor color={isActive ? "primary" : "text"} {...props}>
32
        {children}
33
      </Anchor>
34
    </NextLink>
35
  );
36
}
37

38
Link.Button = function LinkButton({
39
  children,
40
  href,
41
  ...props
42
}: LinkProps) {
43
  return (
44
    <Link
45
      as={Button}
46
      href={href}
47
      sx={{ "&:hover": { textDecoration: "none" } }}
48
      {...props}
49
    >
50
      {children}
51
    </Link>
52
  );
53
};

And just like that we have our fully loaded custom Link component that can handle all of our Next.js routing needs 🔥.

Where's My Link Preview?

Noticed something off? If you've been using browsers long enough, you'll notice that you don't get link previews on the bottom left of your window for some links (just hover over the links to see this). This behaviour can be expected since next/link only exposes a wrapping element that injects the href at runtime. Inspecting the DOM will reveal that the internal link above has no href 🤯!

Fear not, this isn't quite the end, simply pass along the passHref prop to your component and you'll have that sweet mouse over feature back. You can read up on this cool browser feature over here.

Final Thoughts

Hope this tutorial was helpful for those looking to jump into Next.js with a design focused CSS-in-JS framework like Theme-UI.

Similar Posts