React Easy Linkify

React Easy Linkify is a Component of React for finding URL/mentions/hashtags and converting them to Links.

This package is based on Linkifyjs. I rewrote its scanner, React Component, and Plugin Module, make them more flexible.

Very importantly, I made it be supported i18n. You can customize extended characters.

Index

• Demo
• Installation
• Usage
  • Quick Start
  • Options
  • Plugins
    • Mention Plugin
    • Hashtag Plugin
    • Ticket Plugin
  • i18n
• Advanced Usage
  • Plugin Module
  • State Machine
• License
• Contributing

Demo

Open Demo Page

Lanch with Code Sandbox

Installation

NPM

1npm i react-easy-linkify

Or Yarn

1yarn add react-easy-linkify

Usage

Quick Start

Import the Linkify component from react-easy-linkify, and just use it to wrap your elements.

1import React from 'react';
2import './App.css';
3import { Linkify } from 'react-easy-linkify';
4
5const App: React.FC = () => {
6  return (
7    <div className="App">
8      <Linkify>
9        google.com
10        https://google.com
11        https://google.com/search?q=hello你好
12      </Linkify>
13    </div>
14  );
15}
16
17export default App;

Options

Usage

1const App: React.FC = () => {
2  return (
3    <div className="App">
4      <Linkify options={{ className: 'test' }}>
5        google.com
6        https://google.com
7        https://google.com/search?q=hello你好
8      </Linkify>
9    </div>
10  );
11}

The options extend from Linkifyjs's options, currently, they all work properly.

You can check them at Linkifyjs Options.

The following mainly introduces the newly added and important option items in this library.

formatHref

Type: formatHref?: ((href: string, type: LinkEntityType) => string) | Partial<Record<LinkEntityType, (href: string) => string>> | null;

This is useful when finding hashtags and mentions. By formatHref, You can change the default href of <a>.

Useage:

1<Linkify
2  options={{
3    formatHref: {
4      mention: (href) => '/user' + href,
5      hashtag: (href) => '/tag' + href.substring(1),
6    }
7  }}
8></Linkfiy>

The LinkEntityType type has values of url, email, hashtag, and mention.

format

Type: format?: ((value: string, type: LinkEntityType) => string) | Partial<Record<LinkEntityType, (value: string) => string>> | null;

Like formatHref, Format the text displayed. e.g... cutoff a long URL.

1<Linkify
2  options={{
3    format: {
4      url: (value) => value.substr(0, 20),
5    }
6  }}
7></Linkfiy>

linkWrapper

When you need to customize the elements of the link, or You want to add some element in the link's parent. It's very useful.

Option's attributes, className is all of HTML element's attribute, not React node's props.

By this param, It can replace most other params (e.g... attributes, className, target), And make it programable.

Type

1type LinkWrapperType<EXTRA> = React.FC<{
2  options: IOptionsData<EXTRA>;
3  key: string;
4  href: string;
5  className?: string;
6  target?: string;
7  type: LinkEntityType;
8  [key: string]: any;
9}>;
10
11linkWrapper?: LinkWrapperType<EXTRA> | Partial<Record<LinkEntityType, LinkWrapperType<EXTRA>>>;

Useage:

1const App: React.FC = () => {
2  return (
3    <div className="App">
4      <Linkify options={{
5        className: 'test',
6        linkWrapper: (props) => (
7          <div className='wrapper'>
8            <a {...props}>{props.children}</a>
9          </div>
10        ),
11      }}
12      >
13        google.com
14        https://google.com
15        https://google.com/search?q=hello你好
16      </Linkify>
17    </div>
18  );
19}

Or setting of a specific type:

1const App: React.FC = () => {
2  return (
3    <div className="App">
4      <Linkify options={{
5        linkWrapper: {
6          mention: (props) => (
7            <div className='wrapper'>
8              <a {...props}>{props.children}</a>
9            </div>
10          )
11        },
12      }}
13      >
14      </Linkify>
15    </div>
16  );
17}

Plugins

The package build-in three plugins:

• Mention (start with @)
• Hashtag (start with #)
• Ticket (start with &)

You can find and enable them by LinkifyCore.PluginManager.

If you want to change them, LinkifyCore.PluginManager provided the original objects of them.

Mention Plugin

To enable the Mention plugin, you just should call LinkifyCore.PluginManager.enableMention().

1import React from 'react';
2import './App.css';
3import { Linkify, LinkifyCore } from 'react-easy-linkify';
4
5LinkifyCore.PluginManager.enableMention();
6
7const App: React.FC = () => {
8  return (
9    <div className="App">
10      <Linkify>
11        @hello @username1 @123hello
12      </Linkify>
13    </div>
14  );
15}
16
17export default App;

Hashtag Plugin

Like the mention plugin:

1import React from 'react';
2import './App.css';
3import { Linkify, LinkifyCore } from 'react-easy-linkify';
4
5LinkifyCore.PluginManager.enableHashtag();
6
7const App: React.FC = () => {
8  return (
9    <div className="App">
10      <Linkify>
11        #hello #username1 #123hello
12      </Linkify>
13    </div>
14  );
15}
16
17export default App;

Ticket Plugin

The ticket only includes numbers, it's away used in issue or work order.

Tips In the Linkifyjs, the Ticket was started with #. But when it exists with hashtag and i18n, sometimes has been mistakes.

So I fixed it. In this package, the Ticket was starting with &;

1import React from 'react';
2import './App.css';
3import { Linkify, LinkifyCore } from 'react-easy-linkify';
4
5LinkifyCore.PluginManager.enableTicket();
6
7const App: React.FC = () => {
8  return (
9    <div className="App">
10      <Linkify>
11        #hello #username1 #123hello
12      </Linkify>
13    </div>
14  );
15}
16
17export default App;

i18n

The i18n is only needed for Mention and Hashtag. It's not necessary for i18n. If you don't use Mention or Hashtag, maybe you also don't need i18n.

Firstly, You should find the RegExp of the charset of your language or any you're needed.

Then you can call the method of LinkifyCore.addCharsSupport to support the language you need.

1LinkifyCore.addCharsSupport(/[\u2E80-\u9FFF]/);

Advanced Usage

The linkify's core is an FSM(finite-state machine), It's work through action and state transfer.

In the original package, it only exported the entry point of the state machine.

So, it's so difficult to modify somethings. But now, in this package, I export many important variables from scanner, and rewrite the plugin module.

You can read the code of this library, I will supplement this part of the document as soon as possible.

Plugin Module

TODO

State Machine

TODO

License

MIT

Contributing

PR and issue are welcome.