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

Jump to bottom

@uppy/react: deprecate useUppy #4223

Merged
merged 7 commits into from
Dec 23, 2022
Merged

@uppy/react: deprecate useUppy #4223

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
66ce650
Deprecate useUppy
Murderlon Nov 16, 2022
76fff17
Simplify dynamic example
Murderlon Nov 16, 2022
1b08f95
Merge branch 'main' into useUppy
Murderlon Dec 14, 2022
dd9a1ed
Update docs
Murderlon Dec 14, 2022
1ad2e97
Apply feedback
Murderlon Dec 19, 2022
a71bce3
Apply suggestion
Murderlon Dec 23, 2022
cf57064
Fix lint error
Murderlon Dec 23, 2022
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
3 changes: 3 additions & 0 deletions packages/@uppy/react/src/useUppy.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
import type Uppy from '@uppy/core'

/**
* @deprecated Initialize Uppy outside of the component.
*/
declare function useUppy(factory: () => Uppy): Uppy

export default useUppy
3 changes: 3 additions & 0 deletions packages/@uppy/react/src/useUppy.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
import { useEffect, useRef } from 'react'
import { Uppy as UppyCore } from '@uppy/core'

/**
* @deprecated Initialize Uppy outside of the component.
*/
export default function useUppy (factory) {
if (typeof factory !== 'function') {
throw new TypeError('useUppy: expected a function that returns a new Uppy instance')
Expand Down
63 changes: 0 additions & 63 deletions website/src/docs/react-initializing.md
View file
Open in desktop

This file was deleted.

68 changes: 24 additions & 44 deletions website/src/docs/react.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,60 +19,40 @@ Install from NPM:
npm install @uppy/react
```

## CSS

Make sure to also include the necessary CSS files for each Uppy React component you are using. Follow links for individual components docs below for details on that.

## Usage

`@uppy/react` exposes component wrappers for `Dashboard`, `DragDrop`, and all other UI elements.
The components can be used with either [React][] or API-compatible alternatives such as [Preact][].

Instead of adding a UI plugin to an Uppy instance with `.use()`, the Uppy instance can be passed into components as an `uppy` prop.
All other props are passed as options to the plugin.
A couple things to keep in mind when using Uppy with React:

* Instead of adding a UI plugin to an Uppy instance with `.use()`, the Uppy instance can be passed into components as an `uppy` prop.
* All other props are passed as options to the plugin.
* The Uppy instance should **not** live inside the component but outside of it.
* You have to pass the IDs of your `use`d plugins to the `plugins` array prop so Dashboard knows it needs to render them.
* An Uppy instance can’t be used by multiple components. Make sure you are using a unique Uppy instance per component.
Murderlon marked this conversation as resolved.
Show resolved Hide resolved

Here is a basic example:

```js
import React from 'react'
import React, { useEffect } from 'react'
import Uppy from '@uppy/core'
import Tus from '@uppy/tus'
import { DragDrop } from '@uppy/react'

const uppy = new Uppy({
meta: { type: 'avatar' },
restrictions: { maxNumberOfFiles: 1 },
autoProceed: true,
})

uppy.use(Tus, { endpoint: '/upload' })

uppy.on('complete', (result) => {
const url = result.successful[0].uploadURL
store.dispatch({
type: 'SET_USER_AVATAR_URL',
payload: { url },
})
})

const AvatarPicker = ({ currentAvatar }) => {
return (
<div>
<img src={currentAvatar} alt="Current Avatar" />
<DragDrop
uppy={uppy}
locale={{
strings: {
// Text to show on the droppable area.
// `%{browse}` is replaced with a link that opens the system file selection dialog.
dropHereOr: 'Drop here or %{browse}',
// Used as the label for the link that opens the system file selection dialog.
browse: 'browse',
},
}}
/>
</div>
)
import Webcam from '@uppy/webcam'
import { Dashboard } from '@uppy/react'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to highlight import Dashboard from '@uppy/react/lib/Dashboard.js'? We probably want to introduce an exports map to sugar code it, but importing the individual modules makes the most sense otherwise you have to fight with peer dependencies.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was hoping to do a separate PR for the exports map next to this so we don't have to document that workaround


const uppy = new Uppy().use(Webcam)

function Component () {
return <Dashboard uppy={uppy} plugins={['Webcam']} />
}
```

## CSS

Make sure to also include the necessary CSS files for each Uppy React component you are using. Follow links for individual components docs below for details on that.

## Components

The following plugins are available as React component wrappers (you need to
install each package separately):

Expand Down