[RFC] New Link component

[flybayer]

Update 12/10/2020

<Link> now works with just href and doesn't require the as prop. You can also use it to link to external sites. But you still can't set className or activeClassName to <Link>.

What do you want and why?

A new Link component that's much easier to use that the default Next.js Link!

1. The Next.js Link component is terribly cumbersome to use:

<Link href="/products/[id]" as={'/products/' + product.id}>
  <a>{product.name}</a>
</Link>

2. You can't use this Link component to link to external sites.
3. You can set className on <Link>
4. It doesn't have a way to set "active link" styles.

Proposal

I think this is the best option I've considered. It's quite natural and intuitive. And it doesn't require you to think about what the actual page is named.

<Link href={'/products/' + product.id}>
  {product.name}
</Link>

Other Next.js link options will still be supported, like replace and scroll

Active Styles

By default, active styles are applied when href === pathname

activeClassName: string

<Link href={'/products/' + product.id} activeClassName="active">
  {product.name}
</Link>

activeStyle: a normal React style object applied when the current link is active

<Link href={'/products/' + product.id} activeStyle={{fontWeight: 'bold'}}>
  {product.name}
</Link>

Partially Active

Sometimes you want a link to be active if there's a partial sub-match instead of a full path match. For this case, you can pass partiallyActive={true}

This example link to /products will show as active when the current path is /products/1.

<Link href="/products" activeClassName="active" partiallyActive={true}>
  {product.name}
</Link>

Linking to External Sites

We can support linking to other sites by rendering a plain <a> tag if href includes a protocol (://)

<Link href="http://blitzjs.com">
  Blitz
</Link>

<Link href="mailto://hey@example.com">
  Blitz
</Link>

Href as an Object

Same format as Next.js

<Link href={{ pathname: '/products/' + product.id, query: { sort: 'asc' } }}>
  {product.name}
</Link>

Converting Next apps to Blitz apps

People with existing Next apps will be importing Link from next/link, so this will continue to work as expected. But if they change to import Link from blitz, then they will need to update the usage of Link. This could probably be done via a codemod.

Implementation

This is complex to implement because we must compute a route manifest at build time and use that during runtime to map this api to what Next requires. But it's totally possible.

• We need to use React.forwardRef

---

What do you all think about this? Any other rough spots with the Next.js Link that we can improve?

Similar discussion in the Next.js repo: vercel/next.js#8207

[merelinguist]

Yes yes yes! Looks awesome!

[oleksify]

I think it would be great to expose a function to figure out if link is active. The === is not always the rule. You may have subpath, but you want to highlight parent as active.

[flybayer]

We could definitely do this, but you can still accomplish this without exposing a function on <Link>.

import { Link, useRouter } from 'blitz'

export default function ActiveParentLink({ children, href }) {
  const router = useRouter()

  const style = {
    color: router.pathname.includes(href) ? 'red' : 'black',
  }

  return (
    <Link href={href} style={style}>
      {children}
    </Link>
  )
}

If we added this to <Link> what would the function API look like?

[flybayer]

Update: I added the partiallyActive={true} prop to cover cases like this. I discovered Gatsby has this, and I think it's a great idea.

[ryardley]

Great idea. Not so sure about the idea of including styling within the link component. Ideally we want to manage the link behaviour and stay out of styling. In fact we would probably want to delegate all styling to whatever system the user is using such as styled-components etc. I would vote for a render prop to manage active etc.

<Link href={'/products/' + product.id} >
  {({active}) => (
    <MyStyledProductName active={active}>product.name</MyStyledProductName>
  )}
</Link>

[flybayer]

activeClassName and activeStyle is exactly how React Router (and by extension, Gatsby) does it, and it works very well. Works with styled components too.

const Link = styled(BlitzLink)`
  color: black;
  
  &.active {
    color: purple;
  }
`

<Link href="/" activeClassName="active">Home</Link>

[merelinguist]

Yeah activeClassName is imo the simplest way to enable styling support. Plus, since there's precedent like Brandon mentions, it means it’s easier for peeps to find examples of activeClassName with whatever styling library they’re using.

[franky47]

For the linking to external sites, it would be probably better to always render an anchor tag, for semantics and routing to work the hard way if the bundle is not finished loading/hydrating.

Also, mailto addresses can also be mailto:foo@bar.com, without the double slash.

[flybayer]

Absolutely. What I meant is that we render an element without the Next router attached to it.

[cr101]

Perhaps these improvements could be proposed to be implemented in Next.js core

[flybayer]

I doubt it. 😕 Especially because this would have breaking changes and they don't make breaking changes. Also there's multiple issues with people wanting to add things like activeClassName and their solution was to add useRouter and withRouter

[merelinguist]

NB though that they do plan to solve part of this RFC (automatically handling dynamic routes without the double href / as props): vercel/next.js#8207

[flybayer]

Update

Here's a custom <Link> component I started using on a project. It can be used like this:

<Link page="/users/[id]" params={{ id: user.id }}>
  {user.name}
</Link>

<Link page="/blog/[...slug]" params={{ slug: ['coffee', 'frenchpress'] }}>
  View Here
</Link>

It's a lot better than the default Next.js and could be a good option to add to Blitz. But I think only having a single href prop like my initial proposal is still better?

What do y'all think?

[wKovacs64]

I'm in favor. And a single prop sounds good!

[flybayer]

So the API in my original post or this one?

[wKovacs64]

Sorry, misread/misunderstood. I prefer the original proposal.

[remidej]

Hello! I think providing our own Link component may not be the best solution. Next, React-Router and Reach Router already have theirs. I think having yet another Link API will be confusing for many users.

But I think Blitz is in a unique position to solve the links problem. Unlike the routing libraries I mentioned, we have a build process to compile a Blitz app to a Next app. I think we could use that moment to transform plain <a> tags to Next Link components.

I think this the best of both worlds. Users don't have another API to learn, they just write <a> tags like they did before. But we also get client-side page transitions for these pages.

I think this would add more magic to the Blitz experience, just like importing backend functions in React.

[remidej]

Thanks for your reply. In what case do you think users would need <a> tags without magic? Apart from external links, which are easy to detect. But if it does come up, I could see 3 ways to opt out of the magic:

• <a data-blitz="false">: data attributes are not very React-y, but they could work
• Enter an absolute URL as the href, instead of a relative path
• Manually update the location in the onClick with window.location.href = '/mynewpath'

None is ideal, but again, I think these cases would be quite rare.

About activeClassName, I'm not sure I understand the pain point. I feel like instead of a class name, we could apply styles with the :active CSS selectors, though I may be missing something.

edit: I found this closed Next.js PR on the topic. I think activeClassName may be necessary for React Router because they abstract the <a> tag entirely, which is not the case of Next.

As for partiallyActive, it doesn't have a CSS selector, so I don't know. But even if we don't figure it out, I think it's not worth the trade-off of dealing with a Link component.

So I don't have all answers, but I just want to suggest a new direction. As React developers, we want to make components for everything, but it's good to stay close to the standards when we can.

[ryardley]

We have to be careful to accomodate the case of UI kits as well such as Material UI etc. Where you might pass a link component to a special styled component which is really difficult to manage with compile time transforms. This might mean something like <Link component= “a” /> not sure this is something you can solve without some kind of monkey patch/polyfill approach or providing your own link component.

[flybayer]

Adding to @ryardley's comment, anyone using components created via the emotion or styled-components styled() API will have custom link components like <A> or <Link> and <ButtonLink>.

If we make magic <a> tags, the end-result will still be the Next.js <Link> component. So I think it probably makes sense to go ahead and create our own <Link> component that people can use with UI libraries, etc. Then if/when we add magic <a> tags, the build will convert <a> to our custom <Link> component.

Another benefit of going ahead and making a custom link component is that we can do this relatively quickly and people can start using it. But magic <a> will need a lot of R&D.

What do you think?

[remidej]

I like the idea of providing both. This way, we can use <a> tags most of the time, but provide a more thorough component when needed, for example to use it in a design system. And it seems more agile, we can release the Link right away, then later magic <a> tags when they're ready.

The drawback is that it can be confusing. People don't like having two tools to do the same thing, or having to convert one to the other when they reach the limits of <a> tags.

Considering this, do you think it would be a good feature?

[flybayer]

Considering this, do you think it would be a good feature?

Assuming you are referring to magic <a> tags, honestly I don't know. If it was up to me, I wouldn't add it, at least at this point. But I'm not necessarily opposed to it if sufficient people want it and if we can come up with a good enough implementation.

[Skn0tt]

By default, active styles are applied when href === pathname

Just as a reminder in case this gets implemented: Next.js' baseUrl needs to be accounted for :D