@uppy/react: deprecate useUppy

packages/@uppy/react/src/useUppy.d.ts

@@ -1,5 +1,8 @@
 import type Uppy from '@uppy/core'
 
+/**
+ * @deprecated Initialize Uppy outside of the component or with `useState` and `useEffect` (see docs)
+ */
 declare function useUppy(factory: () => Uppy): Uppy
 
 export default useUppy

packages/@uppy/react/src/useUppy.js

@@ -1,6 +1,9 @@
 import { useEffect, useRef } from 'react'
 import { Uppy as UppyCore } from '@uppy/core'
 
+/**
+ * @deprecated Initialize Uppy outside of the component or with `useState` and `useEffect` (see docs)
+ */
 export default function useUppy (factory) {
   if (typeof factory !== 'function') {
     throw new TypeError('useUppy: expected a function that returns a new Uppy instance')

website/src/docs/react.md

@@ -19,10 +19,6 @@ 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
 
 The components can be used with either [React][] or API-compatible alternatives such as [Preact][].
@@ -31,48 +27,55 @@ Instead of adding a UI plugin to an Uppy instance with `.use()`, the Uppy instan
 All other props are passed as options to the plugin.
 
 ```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 { Dashboard } from '@uppy/react'
+
+const uppy = new Uppy()
+
+function Component () {
+  useEffect(() => {
+    return () => {
+      uppy.close({ reason: 'unmount' })
+    }
+  }, [])
+
+  return <Dashboard uppy={uppy} />
 }
 ```
 
+### Dynamic options
+
+```js
+import React, { useState, useEffect } from 'react'
+import Uppy from '@uppy/core'
+import { Dashboard } from '@uppy/react'
+
+const uppy = new Uppy()
+
+function Component ({ restrictions }) {
+  useEffect(() => {
+    // Change @uppy/core options
+    uppy.setOptions({ restrictions })
+
+    // Or change some plugin dynamically
+    uppy.getPlugin('SomePlugin').setOptions({ /* options */ })
+
+    return () => {
+      uppy.close({ reason: 'unmount' })
+    }
+  }, [restrictions])
+
+  return <Dashboard uppy={uppy} />
+}
+```
+
+## 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):