-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: updated readme.md in the react uploader
- Loading branch information
1 parent
052bad0
commit 0b9c99e
Showing
2 changed files
with
154 additions
and
134 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,18 +1,118 @@ | ||
# Uploadcare React components | ||
<p align="center"> | ||
<a href="https://uploadcare.com/?ref=react-uploader"> | ||
<picture> | ||
<source media="(prefers-color-scheme: light)" srcset="https://ucarecdn.com/1b4714cd-53be-447b-bbde-e061f1e5a22f/logosafespacetransparent.svg"> | ||
<source media="(prefers-color-scheme: dark)" srcset="https://ucarecdn.com/3b610a0a-780c-4750-a8b4-3bf4a8c90389/logotransparentinverted.svg"> | ||
<img width=250 alt="Uploadcare logo" src="https://ucarecdn.com/1b4714cd-53be-447b-bbde-e061f1e5a22f/logosafespacetransparent.svg"> | ||
</picture> | ||
</a> | ||
</p> | ||
<p align="center"> | ||
<a href="https://uploadcare.com/?ref=react-uploader">Website</a> • | ||
<a href="https://uploadcare.com/docs/file-uploader?ref=react-uploader">Docs</a> • | ||
<a href="https://uploadcare.com/blog?ref=react-uploader">Blog</a> • | ||
<a href="https://discord.gg/mKWRgRsVz8?ref=react-uploader">Discord</a> • | ||
<a href="https://twitter.com/Uploadcare?ref=react-uploader">Twitter</a> | ||
</p> | ||
|
||
<a href="https://uploadcare.com/?utm_source=github&utm_campaign=uploadcare-js-api-clients"> | ||
<img align="right" width="64" height="64" | ||
src="https://ucarecdn.com/edfdf045-34c0-4087-bbdd-e3834921f890/userpiccircletransparent.svg" | ||
alt=""> | ||
</a> | ||
# Uploadcare React Uploader | ||
|
||
Uploadcare React components for browsers. Includes an adapter that facilitates the conversion from a web component to a React component. And react components uploader. | ||
[![NPM version][npm-img]][npm-url] | ||
[![Build Status][badge-build]][build-url] | ||
[![GitHub release][badge-release-img]][badge-release-url] | ||
[![Uploadcare stack on StackShare][badge-stack-img]][badge-stack-url] | ||
|
||
Welcome to the Uploadcare React Uploader documentation! | ||
This documentation provides guidance on how to use the Uploadcare React Uploader in your projects, along with details | ||
about its features, installation process, usage examples, customization options, event handling, and security | ||
considerations. | ||
|
||
## Packages | ||
<img alt="Uploadcare File Uploader examples" src="https://ucarecdn.com/916a1054-ca44-4c4a-9f7b-99fa499043d9/-/preview/"> | ||
|
||
* [**@uploadcare/react-adapter**](./packages/react-adapter/README.md) | ||
* [**@uploadcare/react-uploader**](./packages/react-uploader/README.md) | ||
|
||
## Quick start | ||
### From NPM: | ||
1. Install the package: `npm install @uploadcare/react-uploader` | ||
2. Connect React Uploader from your script file: | ||
```jsx | ||
import { FileUploaderRegular } from "@uploadcare/react-uploader"; | ||
import "@uploadcare/react-uploader/core.css"; | ||
|
||
<FileUploaderRegular pubkey="YOUR_PUBLIC_KEY"/>; | ||
``` | ||
|
||
## Styles | ||
You can customize the appearance of the React Uploader by using the `className` prop, which lets you apply custom CSS classes to the `FileUploader` wrapper, including the `Regular`, `Minimal`, and `Inline` variations. | ||
|
||
```jsx | ||
import { FileUploaderRegular } from "@uploadcare/react-uploader"; | ||
import "@uploadcare/react-uploader/core.css"; | ||
|
||
<FileUploaderRegular className="fileUploaderWrapper" pubkey="YOUR_PUBLIC_KEY"/>; | ||
``` | ||
|
||
```css | ||
.fileUploaderWrapper uc-file-uploader-regular { | ||
} | ||
``` | ||
|
||
## Props | ||
An easy way to connect React Uploader to your project and utilize the available API props. | ||
We provide a full set of props that are used in File Uploader. For review we suggest you to look at the [documentation][uc-docs-file-uploader-options]. | ||
|
||
## File Uploader API | ||
|
||
For convenience, we provide the ability to access the File Uploader API using `apiRef`. | ||
You can see what methods are available in `apiRef` in the [documentation][uc-docs-file-uploader-api]. | ||
It is important to note that we now pass all InstanceType from UploadCtxProvider. | ||
|
||
```jsx | ||
import React, {useRef, useEffect} from "react"; | ||
import { | ||
FileUploaderRegular, | ||
UploadCtxProvider | ||
} from "@uploadcare/react-uploader"; | ||
import "@uploadcare/react-uploader/core.css"; | ||
|
||
const Example = () => { | ||
const uploaderRef = useRef <InstanceType<UploadCtxProvider> | null>(null); | ||
|
||
<FileUploaderRegular apiRef={uploaderRef} pubkey="YOUR_PUBLIC_KEY"/>; | ||
} | ||
``` | ||
|
||
## Events | ||
Events in React Uploader are the same as in File Uploader, see the [documentation][uc-docs-events]. | ||
The principle of converting events from blocks to React Uploader: | ||
|
||
1. All events in React Uploader start with `on`. | ||
2. All events in React Uploader in `camelCase`. | ||
|
||
```jsx | ||
import { FileUploaderRegular } from "@uploadcare/react-uploader"; | ||
import "@uploadcare/react-uploader/core.css"; | ||
|
||
<FileUploaderRegular | ||
pubkey="YOUR_PUBLIC_KEY" | ||
onModalOpen={() => { | ||
console.log('modal-open') | ||
}} | ||
/> | ||
``` | ||
|
||
## Next.js | ||
File Uploader does not support Server-side Rendering (SSR), we have a special import for nextjs that already has SSR disabled. | ||
You will need to import with import `@uploadcare/react-uploader/next` | ||
|
||
```jsx | ||
'use client' | ||
import { FileUploaderRegular } from "@uploadcare/react-uploader/next"; | ||
import "@uploadcare/react-uploader/core.css"; | ||
|
||
function App() { | ||
return <FileUploaderRegular pubkey="YOUR_PUBLIC_KEY" /> | ||
}; | ||
``` | ||
|
||
## Security issues | ||
|
||
|
@@ -29,18 +129,19 @@ Issues and PRs are welcome. You can provide your feedback or drop us a support | |
request at [[email protected]][uc-email-hello]. | ||
|
||
[uc-email-bounty]: mailto:[email protected] | ||
|
||
[uc-email-hello]: mailto:[email protected] | ||
[github-releases]: https://github.com/uploadcare/react-uploader/releases | ||
[github-branch-release]: https://github.com/uploadcare/react-uploader/tree/release | ||
[github-contributors]: https://github.com/uploadcare/react-uploader/graphs/contributors | ||
[badge-stack-img]: https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat | ||
[badge-stack-url]: https://stackshare.io/uploadcare/stacks/ | ||
[badge-release-img]: https://img.shields.io/github/release/uploadcare/uploadcare-js-api-clients.svg | ||
[badge-release-img]: https://img.shields.io/github/release/uploadcare/react-components.svg | ||
[badge-release-url]: https://github.com/uploadcare/react-uploader/releases | ||
[npm-img]: http://img.shields.io/npm/v/@uploadcare/upload-client.svg | ||
[npm-url]: https://www.npmjs.org/package/@uploadcare/upload-client | ||
[npm-img]: http://img.shields.io/npm/v/@uploadcare/react-uploader.svg | ||
[npm-url]: https://www.npmjs.com/package/@uploadcare/react-uploader | ||
[badge-build]: https://github.com/uploadcare/react-uploader/actions/workflows/checks.yml/badge.svg | ||
[build-url]: https://github.com/uploadcare/react-uploader/actions/workflows/checks.yml | ||
[uc-docs-upload-api]: https://uploadcare.com/docs/api_reference/upload/?utm_source=github&utm_campaign=uploadcare-js-api-clients | ||
[uc-docs-metadata]: https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/File-Metadata | ||
|
||
[uc-docs-events]: https://uploadcare.com/docs/file-uploader/events/ | ||
[uc-docs-file-uploader-api]: https://uploadcare.com/docs/file-uploader/api | ||
[uc-docs-file-uploader-options]: https://uploadcare.com/docs/file-uploader/options/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,98 +1,48 @@ | ||
# Uploadcare React Uploader | ||
|
||
<a href="https://uploadcare.com/?utm_source=github&utm_campaign=uploadcare-js-api-clients"> | ||
<img align="right" width="64" height="64" | ||
src="https://ucarecdn.com/edfdf045-34c0-4087-bbdd-e3834921f890/userpiccircletransparent.svg" | ||
alt=""> | ||
</a> | ||
<p align="center"> | ||
<a href="https://uploadcare.com/?ref=react-uploader"> | ||
<picture> | ||
<source media="(prefers-color-scheme: light)" srcset="https://ucarecdn.com/1b4714cd-53be-447b-bbde-e061f1e5a22f/logosafespacetransparent.svg"> | ||
<source media="(prefers-color-scheme: dark)" srcset="https://ucarecdn.com/3b610a0a-780c-4750-a8b4-3bf4a8c90389/logotransparentinverted.svg"> | ||
<img width=250 alt="Uploadcare logo" src="https://ucarecdn.com/1b4714cd-53be-447b-bbde-e061f1e5a22f/logosafespacetransparent.svg"> | ||
</picture> | ||
</a> | ||
</p> | ||
<p align="center"> | ||
<a href="https://uploadcare.com/?ref=react-uploader">Website</a> • | ||
<a href="https://uploadcare.com/docs/file-uploader?ref=react-uploader">Docs</a> • | ||
<a href="https://uploadcare.com/blog?ref=react-uploader">Blog</a> • | ||
<a href="https://discord.gg/mKWRgRsVz8?ref=react-uploader">Discord</a> • | ||
<a href="https://twitter.com/Uploadcare?ref=react-uploader">Twitter</a> | ||
</p> | ||
|
||
Welcome to the Uploadcare React Uploader documentation! | ||
This library allows you to seamlessly integrate Uploadcare file uploader into your React applications while adhering to | ||
React principles. | ||
# Uploadcare React Uploader | ||
|
||
[![Build Status][badge-build]][build-url] | ||
[![NPM version][npm-img]][npm-url] | ||
[![Build Status][badge-build]][build-url] | ||
[![GitHub release][badge-release-img]][badge-release-url] | ||
[![Uploadcare stack on StackShare][badge-stack-img]][badge-stack-url] | ||
|
||
* [Summary about project](#summary-about-project) | ||
* [Quick Features](#quick-features) | ||
* [Install](#install) | ||
* [Common](#common) | ||
* [Usage](#usage) | ||
* [Regular](#regular) | ||
* [Inline](#inline) | ||
* [Minimal](#minimal) | ||
* [Props API](#props-api) | ||
* [Styles](#styles) | ||
* [File Uploader API](#file-uploader-api) | ||
* [Events](#events) | ||
* [Next.js](#nextjs) | ||
* [Security issues](#security-issues) | ||
* [Feedback](#feedback) | ||
|
||
## Summary about project | ||
|
||
Welcome to the Uploadcare React Uploader documentation! | ||
This documentation provides guidance on how to use the Uploadcare React Uploader in your projects, along with details | ||
about its features, installation process, usage examples, customization options, event handling, and security | ||
considerations. | ||
|
||
## Quick Features | ||
|
||
- Seamless integration with React applications | ||
- Three different upload options: Regular, Inline, and Minimal | ||
- Customizable styles | ||
- Access to File Uploader API | ||
- Comprehensive event handling | ||
|
||
## Install | ||
|
||
```bash | ||
npm i @uploadcare/react-uploader | ||
``` | ||
<img alt="Uploadcare File Uploader examples" src="https://ucarecdn.com/916a1054-ca44-4c4a-9f7b-99fa499043d9/-/preview/"> | ||
|
||
## Usage | ||
|
||
The Uploadcare React Uploader offers three main components for integration. | ||
Each component serves specific use cases and can be easily implemented into your project. | ||
|
||
### Regular | ||
|
||
## Quick start | ||
### From NPM: | ||
1. Install the package: `npm install @uploadcare/react-uploader` | ||
2. Connect React Uploader from your script file: | ||
```jsx | ||
import { FileUploaderRegular } from "@uploadcare/react-uploader"; | ||
import "@uploadcare/react-uploader/core.css"; | ||
|
||
<FileUploaderRegular pubkey="YOUR_PUBLIC_KEY"/>; | ||
``` | ||
|
||
### Inline | ||
|
||
```jsx | ||
import { FileUploaderInline } from "@uploadcare/react-uploader"; | ||
import "@uploadcare/react-uploader/core.css"; | ||
|
||
<FileUploaderInline pubkey="YOUR_PUBLIC_KEY"/>; | ||
``` | ||
|
||
### Minimal | ||
|
||
```jsx | ||
import { FileUploaderMinimal } from "@uploadcare/react-uploader"; | ||
import "@uploadcare/react-uploader/core.css"; | ||
|
||
<FileUploaderMinimal pubkey="YOUR_PUBLIC_KEY"/>; | ||
``` | ||
|
||
## Props API | ||
|
||
An easy way to connect React-Uploader to your project and utilize the available API props. | ||
We provide a full set of props that are used in blocks. For review we suggest you to look at | ||
the [documentation][uc-docs-file-uploader-options]. | ||
|
||
## Styles | ||
|
||
You can customize the appearance of the React uploader using the className prop, which allows you to add custom CSS | ||
classes to the uploader `FileUploader[Regular | Minimal | Inline]` wrapper. | ||
You can customize the appearance of the React Uploader by using the `className` prop, which lets you apply custom CSS classes to the `FileUploader` wrapper, including the `Regular`, `Minimal`, and `Inline` variations. | ||
|
||
```jsx | ||
import { FileUploaderRegular } from "@uploadcare/react-uploader"; | ||
|
@@ -106,6 +56,10 @@ import "@uploadcare/react-uploader/core.css"; | |
} | ||
``` | ||
|
||
## Props | ||
An easy way to connect React Uploader to your project and utilize the available API props. | ||
We provide a full set of props that are used in File Uploader. For review we suggest you to look at the [documentation][uc-docs-file-uploader-options]. | ||
|
||
## File Uploader API | ||
|
||
For convenience, we provide the ability to access the File Uploader API using `apiRef`. | ||
|
@@ -128,15 +82,12 @@ const Example = () => { | |
``` | ||
|
||
## Events | ||
|
||
Events in React Uploader are the same as in blocks, see the [documentation][uc-docs-events]. | ||
Events in React Uploader are the same as in File Uploader, see the [documentation][uc-docs-events]. | ||
The principle of converting events from blocks to React Uploader: | ||
|
||
1. All events in React Uploader start with `on`. | ||
2. All events in React Uploader in `camelCase`. | ||
|
||
Example: | ||
|
||
```jsx | ||
import { FileUploaderRegular } from "@uploadcare/react-uploader"; | ||
import "@uploadcare/react-uploader/core.css"; | ||
|
@@ -149,29 +100,6 @@ import "@uploadcare/react-uploader/core.css"; | |
/> | ||
``` | ||
|
||
### Table of events | ||
|
||
| Events blocks | Events React Uploader | | ||
|------------------------|------------------------| | ||
| file-added | onFileAdded | | ||
| file-removed | onFileRemoved | | ||
| file-upload-start | onFileUploadStart | | ||
| file-upload-progress | onFileUploadProgress | | ||
| file-upload-success | onFileUploadSuccess | | ||
| file-upload-failed | onFileUploadFailed | | ||
| file-url-changed | onFileUrlChanged | | ||
| modal-open | onModalOpen | | ||
| modal-close | onModalClose | | ||
| done-click | onDoneClick | | ||
| upload-click | onUploadClick | | ||
| activity-change | onActivityChange | | ||
| common-upload-start | onCommonUploadStart | | ||
| common-upload-progress | onCommonUploadProgress | | ||
| common-upload-success | onCommonUploadSuccess | | ||
| common-upload-failed | onCommonUploadFailed | | ||
| change | onChange | | ||
| group-created | onGroupCreated | | ||
|
||
## Next.js | ||
File Uploader does not support Server-side Rendering (SSR), we have a special import for nextjs that already has SSR disabled. | ||
You will need to import with import `@uploadcare/react-uploader/next` | ||
|
@@ -186,7 +114,6 @@ function App() { | |
}; | ||
``` | ||
|
||
|
||
## Security issues | ||
|
||
If you think you ran into something in Uploadcare libraries that might have | ||
|
@@ -202,27 +129,19 @@ Issues and PRs are welcome. You can provide your feedback or drop us a support | |
request at [[email protected]][uc-email-hello]. | ||
|
||
[uc-email-bounty]: mailto:[email protected] | ||
|
||
[uc-email-hello]: mailto:[email protected] | ||
|
||
[github-releases]: https://github.com/uploadcare/react-uploader/releases | ||
[github-branch-release]: https://github.com/uploadcare/react-uploader/tree/release | ||
[github-contributors]: https://github.com/uploadcare/react-uploader/graphs/contributors | ||
[badge-stack-img]: https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat | ||
|
||
[badge-stack-url]: https://stackshare.io/uploadcare/stacks/ | ||
|
||
[badge-release-img]: https://img.shields.io/github/release/uploadcare/react-components.svg | ||
|
||
[badge-release-url]: https://github.com/uploadcare/react-components/releases | ||
|
||
[badge-release-url]: https://github.com/uploadcare/react-uploader/releases | ||
[npm-img]: http://img.shields.io/npm/v/@uploadcare/react-uploader.svg | ||
|
||
[npm-url]: https://www.npmjs.com/package/@uploadcare/react-uploader | ||
|
||
[badge-build]: https://github.com/uploadcare/react-components/actions/workflows/checks.yml/badge.svg | ||
|
||
[build-url]: https://github.com/uploadcare/react-components/actions/workflows/checks.yml | ||
[badge-build]: https://github.com/uploadcare/react-uploader/actions/workflows/checks.yml/badge.svg | ||
[build-url]: https://github.com/uploadcare/react-uploader/actions/workflows/checks.yml | ||
|
||
[uc-docs-events]: https://uploadcare.com/docs/file-uploader/events/ | ||
|
||
[uc-docs-file-uploader-api]: https://uploadcare.com/docs/file-uploader/api | ||
|
||
[uc-docs-file-uploader-options]: https://uploadcare.com/docs/file-uploader/options/ | ||
[uc-docs-file-uploader-options]: https://uploadcare.com/docs/file-uploader/options/ |