Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: updated readme.md in the react uploader #49

Merged
merged 2 commits into from
Oct 31, 2024
Merged

docs: updated readme.md in the react uploader #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
10ec70b
docs: updated readme.md in the react uploader
egordidenko Oct 7, 2024
b23873e
Update README.md
egordidenko Oct 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 118 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,119 @@
# 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"/>;
```

## 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 you need to use `InstanceType` utility type to define `apiRef` type.

```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')
}}
/>
```


## 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 {
}
```

## 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

Expand All @@ -29,18 +130,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/
180 changes: 50 additions & 130 deletions packages/react-uploader/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,110 +1,49 @@
# 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
<img alt="Uploadcare File Uploader examples" src="https://ucarecdn.com/916a1054-ca44-4c4a-9f7b-99fa499043d9/-/preview/">

## Install

```bash
npm i @uploadcare/react-uploader
```

## 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.

```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

Expand All @@ -128,15 +67,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";
Expand All @@ -149,28 +85,21 @@ 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 |

## 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 {
}
```

## Next.js
File Uploader does not support Server-side Rendering (SSR), we have a special import for nextjs that already has SSR disabled.
Expand All @@ -186,7 +115,6 @@ function App() {
};
```


## Security issues

If you think you ran into something in Uploadcare libraries that might have
Expand All @@ -202,27 +130,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/