Skip to content

Commit 2413cca

Browse files
joshswanjoshswan
committed
docs: update and improve README
1 parent b22f4e7 commit 2413cca

File tree

1 file changed

+291
-25
lines changed

1 file changed

+291
-25
lines changed

‎README.md

+291-25
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Auto-Linking component for React Native. Parses text and wraps URLs, phone numbe
66

77
## Installation
88

9-
```javascript
9+
```shell
1010
npm install react-native-autolink --save
1111
```
1212

@@ -23,37 +23,303 @@ class MyComponent extends Component {
2323
<Autolink
2424
text="This is the string to parse for urls (https://github.com/joshswan/react-native-autolink), phone numbers (415-555-5555), emails ([email protected]), mentions/handles (@twitter), and hashtags (#exciting)"
2525
hashtag="instagram"
26-
mention="twitter" />
26+
mention="twitter"
27+
/>
2728
);
2829
}
2930
}
3031
```
3132

3233
## Props
3334

34-
**Note: Any props not listed below will be passed through to the main Text node (e.g. style, numberOfLines).**
35-
36-
| Prop | Type | Default | Description |
37-
| ---- | ---- | ------- | ----------- |
38-
| `text` | `String` | | ***Required.*** The string to parse for links. |
39-
| `email` | `Boolean` | `true` | Enable email linking (`mailto:{email}`). |
40-
| `hashtag` | `Boolean/String` | `false` | Enable hashtag linking to supplied service. Possible values: `false`, `"facebook"`, `"instagram"`, `"twitter"`. |
41-
| `latlng` | `Boolean` | `false` | *Experimental* Enable latitude, longitude linking to maps. |
42-
| `mention` | `Boolean/String` | `false` | Enable mention/handle linking to supplied service. Possible values: `false`, `"instagram"`, `"soundcloud"`, `"twitter"`. |
43-
| `phone` | `Boolean/String` | `true` | Enable phone linking (`tel:{number}`, `sms:{number}`) for calling/texting. Possible values: `false`, `"text"`|
44-
| `twitter` | `Boolean` | `false` | **DEPRECATED. Use `mention` prop.** Enable Twitter handle linking (`twitter://user?screen_name={handle}`). |
45-
| `url` | `Boolean/Object` | `true` | Enable url linking (`https://{url}`). Possible values: `true`, `false`, `{ schemeMatches: true/false, wwwMatches: true/false, tldMatches: true/false }` |
46-
| `stripPrefix` | `Boolean` | `true` | Enable stripping of protocol from link text (`https://url` -> `url`). |
47-
| `stripTrailingSlash` | `Boolean` | `true` | Enable stripping of trailing slashs from link text (`example.com/page/` -> `example.com/page`). |
48-
| `linkStyle` | `TextStyle` | | Custom styling to apply to Text nodes of links. |
49-
| `onPress` | `function` | | Custom function handler for link press events. Arguments: `url:String`, [`match:Object`][match-url]. |
50-
| `onLongPress` | `function` | | Function handler for long press events. Arguments: `url:String`, [`match:Object`][match-url] |
51-
| `renderLink` | `function` | | Custom render function for rendering link nodes. Arguments: `text:String`, [`match:Object`][match-url], `index:Number`. |
52-
| `showAlert` | `Boolean` | `false` | Displays an alert before leaving the app to help with accidental clicks. Possible values: `true`, `false` |
53-
| `truncate` | `Number` | `32` | Truncate long link text for display (e.g. `https://www.google.com/../something.html`). Possible values: `0` to disable, `1+` to truncate to that maximum length. |
54-
| `truncateChars` | `String` | `..` | Characters to replace truncated url segments with, if enabled. |
55-
| `truncateLocation` | `String` | `"smart"` | Specify location of truncation. Possible values: `"smart"`, `"end"`, `"middle"`. |
56-
| `webFallback` | `Boolean` | Android: `true` iOS: `false` | Link to web versions of Instagram/Twitter for hashtag and mention links when users don't have the respective app installed. *Requires `LSApplicationQueriesSchemes` on iOS. See: https://facebook.github.io/react-native/docs/linking.html* |
35+
- [`component?`](#component)
36+
- [`email?`](#email)
37+
- [`hashtag?`](#hashtag)
38+
- [`latlng?`](#latlng)
39+
- [`linkProps?`](#linkprops)
40+
- [`linkStyle?`](#linkstyle)
41+
- [`mention?`](#mention)
42+
- [`onPress?`](#onpress)
43+
- [`onLongPress?`](#onlongpress)
44+
- [`phone?`](#phone)
45+
- [`renderLink?`](#renderlink)
46+
- [`renderText?`](#rendertext)
47+
- [`showAlert?`](#showalert)
48+
- [`stripPrefix?`](#stripprefix)
49+
- [`stripTrailingSlash?`](#striptrailingslash)
50+
- [`text`](#text)
51+
- [`textProps?`](#textprops)
52+
- [`truncate?`](#truncate)
53+
- [`truncateChars?`](#truncatechars)
54+
- [`truncateLocation?`](#truncatelocation)
55+
- [`url?`](#url)
56+
- [`webFallback?`](#webfallback)
57+
58+
**Note:** All other props (e.g. `numberOfLines`, `style`, etc.) will be passed through to the container component, which is either `Text` (default) or a custom component supplied to the `component` prop.
59+
60+
### `component`
61+
62+
| Type | Required | Default | Description |
63+
| ------------------- | -------- | ------- | ----------- |
64+
| React.ComponentType | No | `Text` | Override the component used as the output container. |
65+
66+
```js
67+
<Autolink text={text} component={View} />
68+
```
69+
70+
### `email`
71+
72+
| Type | Required | Default | Description |
73+
| ------- | -------- | ------- | ----------- |
74+
| boolean | No | `true` | Whether to link emails (`mailto:{email}`). |
75+
76+
```js
77+
<Autolink text={text} email={false} />
78+
```
79+
80+
### `hashtag`
81+
82+
| Type | Required | Default | Description |
83+
| ----------------- | -------- | ------- | ----------- |
84+
| boolean or string | No | `false` | Whether to link hashtags to supplied service. Possible values: `false` (disabled), `"facebook"`, `"instagram"`, `"twitter"`. |
85+
86+
```js
87+
<Autolink text={text} hashtag="facebook" />
88+
```
89+
90+
### `latlng`
91+
92+
| Type | Required | Default | Description |
93+
| ------- | -------- | ------- | ----------- |
94+
| boolean | No | `false` | Whether to link latitude, longitude pairs. |
95+
96+
*Warning:* Still experimental.
97+
98+
```js
99+
<Autolink text={text} latlng />
100+
```
101+
102+
### `linkProps`
103+
104+
| Type | Required | Default | Description |
105+
| --------- | -------- | ------- | ----------- |
106+
| TextProps | No | `{}` | Attributes applied to link Text components. |
107+
108+
```js
109+
<Autolink text={text} linkProps={{ suppressHighlighting: true, testID: 'link' }} />
110+
```
111+
112+
### `linkStyle`
113+
114+
| Type | Required | Default | Description |
115+
| --------- | -------- | ------- | ----------- |
116+
| TextStyle | No | `{}` | Styles applied to link Text components. *Note:* Will be overriden if `style` supplied in [`linkProps`](#linkprops). |
117+
118+
```js
119+
<Autolink text={text} linkStyle={{ color: 'blue' }} />
120+
```
121+
122+
### `mention`
123+
124+
| Type | Required | Default | Description |
125+
| ----------------- | -------- | ------- | ----------- |
126+
| boolean or string | No | `false` | Whether to link mentions/handles to supplied service. Possible values: `false` (disabled), `"instagram"`, `"soundcloud"`, `"twitter"`. |
127+
128+
```js
129+
<Autolink text={text} mention="instagram" />
130+
```
131+
132+
### `onPress`
133+
134+
| Type | Required | Default | Description |
135+
| -------- | -------- | ------- | ----------- |
136+
| function | No | | Override default link press behavior. Signature: `(url: string, match: Match) => void`. |
137+
138+
```js
139+
<Autolink
140+
text={text}
141+
onPress={(url, match) => {
142+
switch (match.getType()) {
143+
case 'mention':
144+
Alert.alert('Mention pressed!');
145+
default:
146+
Alert.alert('Link pressed!');
147+
}
148+
}}
149+
/>
150+
```
151+
152+
### `onLongPress`
153+
154+
| Type | Required | Default | Description |
155+
| -------- | -------- | ------- | ----------- |
156+
| function | No | none | Handle link long press events. Signature: `(url: string, match: Match) => void`. |
157+
158+
```js
159+
<Autolink
160+
text={text}
161+
onLongPress={(url, match) => {
162+
switch (match.getType()) {
163+
case 'mention':
164+
Alert.alert('Mention long pressed!');
165+
default:
166+
Alert.alert('Link long pressed!');
167+
}
168+
}}
169+
/>
170+
```
171+
172+
### `phone`
173+
174+
| Type | Required | Default | Description |
175+
| ----------------- | -------- | ------- | ----------- |
176+
| boolean or string | No | `true` | Whether to link phone numbers. Possible values: `false` (disabled), `true` (`tel:{number}`), `"sms"` or `"text"` (`sms:{number}`). |
177+
178+
*Note:* Currently, only US numbers are supported.
179+
180+
```js
181+
<Autolink text={text} phone="sms" />
182+
```
183+
184+
### `renderLink`
185+
186+
| Type | Required | Default | Description |
187+
| -------- | -------- | ------- | ----------- |
188+
| function | No | | Override default link rendering behavior. Signature: `(text: string, match: Match, index: number) => React.ReactNode`. |
189+
190+
*Note:* You'll need to handle press logic yourself when using `renderLink`.
191+
192+
```js
193+
<Autolink
194+
text={text}
195+
component={View}
196+
renderLink={(text, match) => <MyLinkPreviewComponent url={match.getAnchorHref()} />}
197+
/>
198+
```
199+
200+
### `renderText`
201+
202+
| Type | Required | Default | Description |
203+
| -------- | -------- | ------- | ----------- |
204+
| function | No | | Override default text rendering behavior. Signature: `(text: string, index: number) => React.ReactNode`. |
205+
206+
```js
207+
<Autolink
208+
text={text}
209+
component={View}
210+
renderText={(text) => <MyTypographyComponent>{text}</MyTypographyComponent>}
211+
/>
212+
```
213+
214+
### `showAlert`
215+
216+
| Type | Required | Default | Description |
217+
| ------- | -------- | ------- | ----------- |
218+
| boolean | No | `false` | Whether to display an alert before leaving the app (for privacy or accidental clicks). |
219+
220+
```js
221+
<Autolink text={text} showAlert />
222+
```
223+
224+
### `stripPrefix`
225+
226+
| Type | Required | Default | Description |
227+
| ------- | -------- | ------- | ----------- |
228+
| boolean | No | `true` | Whether to strip protocol from URL link text (e.g. `https://github.com` -> `github.com`). |
229+
230+
```js
231+
<Autolink text={text} stripPrefix={false} />
232+
```
233+
234+
### `stripTrailingSlash`
235+
236+
| Type | Required | Default | Description |
237+
| ------- | -------- | ------- | ----------- |
238+
| boolean | No | `true` | Whether to strip trailing slashes from URL link text (e.g. `github.com/` -> `github.com`). |
239+
240+
```js
241+
<Autolink text={text} stripTrailingSlash={false} />
242+
```
243+
244+
### `text`
245+
246+
| Type | Required | Default | Description |
247+
| ------- | -------- | ------- | ----------- |
248+
| string | Yes | | The string to parse for links. |
249+
250+
```js
251+
<Autolink text={text} />
252+
```
253+
254+
### `textProps`
255+
256+
| Type | Required | Default | Description |
257+
| --------- | -------- | ------- | ----------- |
258+
| TextProps | No | `{}` | Attributes applied to non-link Text components. |
259+
260+
```js
261+
<Autolink text={text} textProps={{ selectable: false }} />
262+
```
263+
264+
### `truncate`
265+
266+
| Type | Required | Default | Description |
267+
| --------- | -------- | ------- | ----------- |
268+
| number | No | `32` | Maximum length of URL link text. Possible values: `0` (disabled), `1+` (maximum length). |
269+
270+
```js
271+
<Autolink text={text} truncate={20} />
272+
```
273+
274+
### `truncateChars`
275+
276+
| Type | Required | Default | Description |
277+
| --------- | -------- | ------- | ----------- |
278+
| string | No | `..` | Characters to replace truncated URL link text segments with (e.g. `github.com/../repo`) |
279+
280+
```js
281+
<Autolink text={text} truncateChars="**" />
282+
```
283+
284+
### `truncateLocation`
285+
286+
| Type | Required | Default | Description |
287+
| --------- | -------- | ---------- | ----------- |
288+
| string | No | `"smart"` | Override truncation location. Possible values: `"smart"`, `"end"`, `"middle"`. |
289+
290+
```js
291+
<Autolink text={text} truncateLocation="end" />
292+
```
293+
294+
### `url`
295+
296+
| Type | Required | Default | Description |
297+
| ----------------- | -------- | ------- | ----------- |
298+
| boolean or object | No | `true` | Whether to link URLs. Possible values: `false` (disabled), `true`, `UrlConfig` (see below). |
299+
300+
```js
301+
type UrlConfig = {
302+
// Whether to link URLs prefixed with a scheme (e.g. https://github.com)
303+
schemeMatches?: boolean;
304+
// Whether to link URLs prefix with www (e.g. www.github.com)
305+
wwwMatches?: boolean;
306+
// Whether to link URLs with TLDs but not scheme or www prefixs (e.g. github.com)
307+
tldMatches?: boolean;
308+
};
309+
```
310+
311+
```js
312+
<Autolink text={text} url={false} />
313+
<Autolink text={text} url={{ tldMatches: false }} />
314+
```
315+
316+
### `webFallback`
317+
318+
| Type | Required | Default | Description |
319+
| ------- | -------- | ----------------------------- | ----------- |
320+
| boolean | No | Android: `true`, iOS: `false` | Whether to link to web versions of services (e.g. Facebook, Instagram, Twitter) for hashtag and mention links when users don't have the respective app installed. |
321+
322+
*Note:* Requires `LSApplicationQueriesSchemes` on iOS so it is disabled by default on iOS. See [Linking docs](https://reactnative.dev/docs/linking.html) for more info.
57323

58324
## Supported By
59325

0 commit comments

Comments
 (0)