feat: composable primitive components

docs/src/app/(docs)/concepts/theming/page.mdx

@@ -11,8 +11,20 @@ import * as d from "./demos";
 
 # Theming
 
-Our prebuilt components are customizable so you can make them fit with the theme
-of your application.
+UploadThing ships with a default styled button and dropzone component that you
+can mount in your app if you don't have special needs on design. These default
+components are customizable, both in styling and content. The first parts of
+this doc will cover how to customize the default components and how you can make
+them fit with the theme of your application.
+
+Due to their nature, there are certain customizations you cannot make on the
+default components, which is why we also expose the unstyled,
+[headless primitives](#unstyled-primitive-components). These comes with behavior
+built-in but you have full control over what's rendered when and where.
+
+You can also build a fully custom flow you can opt for the
+[`useUploadThing`](/api-reference/react#use-upload-thing) hook that allows you
+to not only customize the look but also have full control of the behavior.
 
 ## UploadButton Anatomy
 
@@ -509,3 +521,92 @@ type UploadDropzoneProps = {
 <d.CustomContent1 />
 <d.CustomContent2 />
 <d.CustomContent3 />
+
+<div className="mt-16"></div>
+
+# Unstyled Primitive Components
+
+These components allow you to bring your own styling solution while not having
+to implement any of the internals. They accept any normal HTML props and can be
+assigned specific HTML tags through the `as` prop.
+
+<Note>This is currently only implemented by `@uploadthing/react`.</Note>
+
+## Creating the unstyled components
+
+```ts {{ title: 'src/utils/uploadthing.ts' }}
+import { generateUploadPrimitives } from "@uploadthing/react";
+
+import type { OurFileRouter } from "~/server/uploadthing";
+
+export const UT = generateUploadPrimitives<OurFileRouter>();
+```
+
+The returned `UT` object includes the following components:
+
+<Properties>
+
+<Property name="Root" type="component" since="7.2">
+  This is the main provider that accept most of the same props as the default `
+  <UploadButton />` and `<UploadDropzone />` accept.
+</Property>
+
+<Property name="Button" type="component" since="7.2">
+  The button element can be used to open the file selector. If you have auto mode
+  enabled, files are automatically uploaded once they are selected. For manual mode, 
+  a second press on the button will upload the selected files.
+</Property>
+<Property name="Dropzone" type="component" since="7.2">
+  A dropzone area which accepts files to be dropped. As for the button, you may have both
+  auto and manual mode.
+</Property>
+<Property name="AllowedContent" type="component" since="7.2">
+  A text field where you can display what types of files are allowed to be uploaded.
+</Property>
+<Property name="ClearButton" type="component" since="7.2">
+  A button that clears the selected files.
+</Property>
+</Properties>
+
+## Using Unstyled Components
+
+All components accept a children function which allows you to grab any piece of
+internal state. This includes `files`, `state`, `dropzone` state, and many more.
+
+<Note>A children function can also be passed as a prop if you prefer.</Note>
+
+### Example of Dropzone
+
+<Note>
+  The `dropzone` parameter will only be defined from within children of the
+  `Dropzone` component.
+</Note>
+
+```jsx
+<UT.Root endpoint="mockRoute">
+  <UT.Dropzone>
+    {({ state }) => (
+      <div>
+        <p>Drag and drop</p>
+        <UT.Button as="button">
+          {state === "uploading" ? "Uploading" : "Upload file"}
+        </UT.Button>
+        <UT.AllowedContent
+          as="p"
+          style={{ fontSize: 12, width: "fit-content" }}
+        />
+      </div>
+    )}
+  </UT.Dropzone>
+</UT.Root>
+```
+
+### Example of Button
+
+```jsx
+<UT.Root endpoint="mockRoute">
+  <UT.Button>
+    {({ state }) => (state === "uploading" ? "Uploading" : "Upload file")}
+  </UT.Button>
+</UT.Root>
+```

examples/minimal-appdir/src/app/page.tsx

@@ -4,6 +4,7 @@ import {
   UploadButton,
   UploadDropzone,
   useUploadThing,
+  UT,
 } from "~/utils/uploadthing";
 
 export default function Home() {
@@ -70,6 +71,44 @@ export default function Home() {
           await startUpload(files);
         }}
       />
+      <UT.Root
+        endpoint="videoAndImage"
+        onClientUploadComplete={(res) => {
+          console.log(`onClientUploadComplete`, res);
+          alert("Upload Completed");
+        }}
+        onUploadBegin={() => {
+          console.log("upload begin");
+        }}
+      >
+        <UT.Dropzone style={{ marginTop: 24 }}>
+          {({ dropzone, state }) => (
+            <div
+              style={{
+                borderWidth: 2,
+                borderStyle: "dashed",
+                borderColor: dropzone?.isDragActive ? "#2563f5" : "#11182725",
+                padding: 16,
+              }}
+            >
+              <p
+                style={{
+                  width: "fit-content",
+                }}
+              >
+                Drag and drop
+              </p>
+              <UT.Button as="button">
+                {state === "uploading" ? "Uploading" : "Upload file"}
+              </UT.Button>
+              <UT.AllowedContent
+                as="p"
+                style={{ fontSize: 12, width: "fit-content" }}
+              />
+            </div>
+          )}
+        </UT.Dropzone>
+      </UT.Root>
     </main>
   );
 }

examples/minimal-appdir/src/utils/uploadthing.ts

@@ -2,11 +2,13 @@ import {
   generateReactHelpers,
   generateUploadButton,
   generateUploadDropzone,
+  generateUploadPrimitives,
 } from "@uploadthing/react";
 
 import type { OurFileRouter } from "~/server/uploadthing";
 
 export const UploadButton = generateUploadButton<OurFileRouter>();
 export const UploadDropzone = generateUploadDropzone<OurFileRouter>();
+export const UT = generateUploadPrimitives<OurFileRouter>();
 
 export const { useUploadThing } = generateReactHelpers<OurFileRouter>();

examples/minimal-pagedir/src/pages/index.tsx

@@ -2,6 +2,7 @@ import {
   UploadButton,
   UploadDropzone,
   useUploadThing,
+  UT,
 } from "~/utils/uploadthing";
 
 export default function Home() {
@@ -54,6 +55,44 @@ export default function Home() {
           await startUpload([file]);
         }}
       />
+      <UT.Root
+        endpoint="videoAndImage"
+        onClientUploadComplete={(res) => {
+          console.log(`onClientUploadComplete`, res);
+          alert("Upload Completed");
+        }}
+        onUploadBegin={() => {
+          console.log("upload begin");
+        }}
+      >
+        <UT.Dropzone style={{ marginTop: 24 }}>
+          {({ dropzone, state }) => (
+            <div
+              style={{
+                borderWidth: 2,
+                borderStyle: "dashed",
+                borderColor: dropzone?.isDragActive ? "#2563f5" : "#11182725",
+                padding: 16,
+              }}
+            >
+              <p
+                style={{
+                  width: "fit-content",
+                }}
+              >
+                Drag and drop
+              </p>
+              <UT.Button as="button">
+                {state === "uploading" ? "Uploading" : "Upload file"}
+              </UT.Button>
+              <UT.AllowedContent
+                as="p"
+                style={{ fontSize: 12, width: "fit-content" }}
+              />
+            </div>
+          )}
+        </UT.Dropzone>
+      </UT.Root>
     </main>
   );
 }

examples/minimal-pagedir/src/utils/uploadthing.ts

@@ -2,11 +2,13 @@ import {
   generateReactHelpers,
   generateUploadButton,
   generateUploadDropzone,
+  generateUploadPrimitives,
 } from "@uploadthing/react";
 
 import type { OurFileRouter } from "~/server/uploadthing";
 
 export const UploadButton = generateUploadButton<OurFileRouter>();
 export const UploadDropzone = generateUploadDropzone<OurFileRouter>();
+export const UT = generateUploadPrimitives<OurFileRouter>();
 
 export const { useUploadThing } = generateReactHelpers<OurFileRouter>();

examples/with-clerk-appdir/src/app/page.tsx

@@ -2,7 +2,7 @@
 
 import { SignIn, useAuth } from "@clerk/nextjs";
 
-import { UploadButton, UploadDropzone } from "~/utils/uploadthing";
+import { UploadButton, UploadDropzone, UT } from "~/utils/uploadthing";
 
 export default function Home() {
   const { isSignedIn } = useAuth();
@@ -35,6 +35,44 @@ export default function Home() {
           console.log("upload begin");
         }}
       />
+      <UT.Root
+        endpoint="videoAndImage"
+        onClientUploadComplete={(res) => {
+          console.log(`onClientUploadComplete`, res);
+          alert("Upload Completed");
+        }}
+        onUploadBegin={() => {
+          console.log("upload begin");
+        }}
+      >
+        <UT.Dropzone style={{ marginTop: 24 }}>
+          {({ dropzone, state }) => (
+            <div
+              style={{
+                borderWidth: 2,
+                borderStyle: "dashed",
+                borderColor: dropzone?.isDragActive ? "#2563f5" : "#11182725",
+                padding: 16,
+              }}
+            >
+              <p
+                style={{
+                  width: "fit-content",
+                }}
+              >
+                Drag and drop
+              </p>
+              <UT.Button as="button">
+                {state === "uploading" ? "Uploading" : "Upload file"}
+              </UT.Button>
+              <UT.AllowedContent
+                as="p"
+                style={{ fontSize: 12, width: "fit-content" }}
+              />
+            </div>
+          )}
+        </UT.Dropzone>
+      </UT.Root>
       {!isSignedIn ? (
         <div
           style={{

examples/with-clerk-appdir/src/utils/uploadthing.ts

@@ -2,11 +2,13 @@ import {
   generateReactHelpers,
   generateUploadButton,
   generateUploadDropzone,
+  generateUploadPrimitives,
 } from "@uploadthing/react";
 
 import type { OurFileRouter } from "~/server/uploadthing";
 
 export const UploadButton = generateUploadButton<OurFileRouter>();
 export const UploadDropzone = generateUploadDropzone<OurFileRouter>();
+export const UT = generateUploadPrimitives<OurFileRouter>();
 
 export const { useUploadThing } = generateReactHelpers<OurFileRouter>();

examples/with-clerk-pagesdir/src/pages/index.tsx

@@ -1,7 +1,7 @@
 import { Inter } from "next/font/google";
 import { SignIn, useAuth } from "@clerk/nextjs";
 
-import { UploadButton, UploadDropzone } from "~/utils/uploadthing";
+import { UploadButton, UploadDropzone, UT } from "~/utils/uploadthing";
 
 const inter = Inter({ subsets: ["latin"] });
 
@@ -36,6 +36,44 @@ export default function Home() {
           console.log("upload begin");
         }}
       />
+      <UT.Root
+        endpoint="videoAndImage"
+        onClientUploadComplete={(res) => {
+          console.log(`onClientUploadComplete`, res);
+          alert("Upload Completed");
+        }}
+        onUploadBegin={() => {
+          console.log("upload begin");
+        }}
+      >
+        <UT.Dropzone style={{ marginTop: 24 }}>
+          {({ dropzone, state }) => (
+            <div
+              style={{
+                borderWidth: 2,
+                borderStyle: "dashed",
+                borderColor: dropzone?.isDragActive ? "#2563f5" : "#11182725",
+                padding: 16,
+              }}
+            >
+              <p
+                style={{
+                  width: "fit-content",
+                }}
+              >
+                Drag and drop
+              </p>
+              <UT.Button as="button">
+                {state === "uploading" ? "Uploading" : "Upload file"}
+              </UT.Button>
+              <UT.AllowedContent
+                as="p"
+                style={{ fontSize: 12, width: "fit-content" }}
+              />
+            </div>
+          )}
+        </UT.Dropzone>
+      </UT.Root>
       {!isSignedIn ? (
         <div
           style={{

examples/with-clerk-pagesdir/src/utils/uploadthing.ts

@@ -2,11 +2,13 @@ import {
   generateReactHelpers,
   generateUploadButton,
   generateUploadDropzone,
+  generateUploadPrimitives,
 } from "@uploadthing/react";
 
 import type { OurFileRouter } from "~/server/uploadthing";
 
 export const UploadButton = generateUploadButton<OurFileRouter>();
 export const UploadDropzone = generateUploadDropzone<OurFileRouter>();
+export const UT = generateUploadPrimitives<OurFileRouter>();
 
 export const { useUploadThing } = generateReactHelpers<OurFileRouter>();