Skip to content

Commit 323953b

Browse files
azizbechaazizbecha
committed
added initial docs
1 parent 66a4f73 commit 323953b

File tree

1 file changed

+88
-34
lines changed

1 file changed

+88
-34
lines changed

‎README.md‎

Lines changed: 88 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,101 @@
1-
# react-native-preview-url
1+
# React Native Preview Url
22

3-
A React Native component to generate rich link previews by fetching metadata (title, description, images) from URLs. Easily integrate customizable and lightweight link previews into your app.
3+
A React Native library that provides an easy way to fetch and display link previews using the `useUrlPreview` hook and a customizable `<LinkPreview />` component.
4+
It uses our own open-source free open source API `azizbecha-link-preview-api` available on GitHub at [https://github.com/azizbecha/link-preview-api](https://github.com/azizbecha/link-preview-api).
5+
6+
You can use the API for free without an API key or host it yourself if you prefer.
7+
8+
## Features
9+
10+
- Fetches metadata (title, description, images, favicons, etc.) from URLs
11+
- Customizable preview component with styles and fallback support
12+
- Supports timeout and error handling
13+
- Handles URL validation and loading states
414

515
## Installation
616

7-
```sh
17+
```bash
818
npm install react-native-preview-url
19+
# or
20+
yarn add react-native-preview-url
921
```
1022

1123
## Usage
1224

13-
### Props
14-
15-
- url (required)
16-
- timeout (optional)
17-
- onSuccess(metadata => console.log(metdata))
18-
- onError(e => console.log(e))
19-
- titleLines: number
20-
- descriptionLines: number
21-
- onPress: () => void
22-
- containerStyle: ViewStyle
23-
- imageContainerStyle: ViewStyle
24-
- titleStyle: TextStyle
25-
- descriptionStyle: TextStyle
26-
- showUrl: boolean
27-
- hideImage?: boolean = false
28-
- loaderComponent: React.ReactNode
29-
- fallbackImage: ImageSource
30-
31-
- baseUrl(later)
32-
- imageComponent
33-
- placeholderImage
34-
35-
## Contributing
36-
37-
- [Development workflow](CONTRIBUTING.md#development-workflow)
38-
- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
39-
- [Code of conduct](CODE_OF_CONDUCT.md)
25+
### useUrlPreview Hook
4026

41-
## License
27+
```tsx
28+
import { useUrlPreview } from 'react-native-preview-url';
4229

43-
MIT
30+
const { loading, data, error } = useUrlPreview('https://github.com');
31+
```
32+
33+
### `<LinkPreview />` Component
4434

45-
---
35+
```tsx
36+
import React from 'react';
37+
import { LinkPreview } from 'react-native-preview-url';
38+
39+
export const Example = () => (
40+
<LinkPreview
41+
url="https://github.com"
42+
timeout={3000} // optional, default timeout in ms
43+
onSuccess={(metadata) => console.log(metadata)}
44+
onError={(error) => console.error(error)}
45+
onPress={() => console.log('Pressed preview')}
46+
containerStyle={{ margin: 16, borderRadius: 8, backgroundColor: '#fff' }}
47+
imageStyle={{ borderRadius: 8, height: 150 }}
48+
titleStyle={{ fontSize: 18, fontWeight: 'bold' }}
49+
descriptionStyle={{ fontSize: 14, color: '#555' }}
50+
urlStyle={{ fontSize: 12, color: 'grey' }}
51+
titleLines={2}
52+
descriptionLines={3}
53+
showUrl={true}
54+
hideImage={false}
55+
/>
56+
);
57+
```
58+
59+
## Props
60+
61+
| Prop | Type | Required | Default | Description |
62+
| ------------------ | ------------------------------------- | -------- | ------------------- | ---------------------------------------------------- |
63+
| `url` | `string` | Yes | - | The URL to fetch metadata for |
64+
| `timeout` | `number` | No | `3000` | Fetch timeout in milliseconds |
65+
| `onSuccess` | `(data: LinkPreviewResponse) => void` | No | - | Callback when data is successfully fetched |
66+
| `onError` | `(error: string) => void` | No | - | Callback when fetching metadata fails |
67+
| `onPress` | `(url: string) => void` | No | - | Callback when the preview component is pressed |
68+
| `containerStyle` | `ViewStyle` | No | - | Style for the container view |
69+
| `imageStyle` | `ImageStyle` | No | - | Style for the preview image |
70+
| `titleStyle` | `TextStyle` | No | - | Style for the title text |
71+
| `descriptionStyle` | `TextStyle` | No | - | Style for the description text |
72+
| `urlStyle` | `TextStyle` | No | - | Style for the URL text |
73+
| `titleLines` | `number` | No | 2 | Number of lines for title text truncation |
74+
| `descriptionLines` | `number` | No | 4 | Number of lines for description text truncation |
75+
| `showUrl` | `boolean` | No | `true` | Whether to show the URL domain below the description |
76+
| `hideImage` | `boolean` | No | `false` | Whether to hide the preview image |
77+
| `visible` | `boolean` | No | `true` | Whether to show or hide the preview component |
78+
| `loaderComponent` | `ReactNode` | No | `ActivityIndicator` | Custom loading component |
79+
| `fallbackImage` | `ImageSourcePropType` | No | `undefined` | Fallback image in case the website doesn't have one |
80+
81+
## Example Response Object
82+
83+
```json
84+
{
85+
"status": 200,
86+
"title": "GitHub · Build and ship software on a single, collaborative platform",
87+
"description": "Join the world's most widely adopted, AI-powered developer platform where millions of developers, businesses, and the largest open source community build software that advances humanity.",
88+
"url": "https://github.com/",
89+
"images": [
90+
"https://images.ctfassets.net/8aevphvgewt8/4UxhHBs2XnuyZ4lYQ83juV/b61529b087aeb4a318bda311edf4c345/home24.jpg"
91+
],
92+
"favicons": ["https://github.githubassets.com/favicons/favicon.svg"],
93+
"mediaType": "object",
94+
"contentType": "text/html",
95+
"siteName": "GitHub"
96+
}
97+
```
98+
99+
## License
46100

47-
Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
101+
MIT License

0 commit comments

Comments
 (0)