feat: customisable composable components

[veloii]

Describe the feature you'd like to request

I'd like to request unstyled, composable components for uploadthing:

• Inline uploadable image component (e.g. for avatars)
• Composable versions of existing file upload components

These would be bare-bones, allowing easy styling and flexible combinations. I've already had to build similar things for my own sites. This kind of stuff is gold for DX - saves time and headaches.

Describe the solution you'd like to see

I've already got an UploadableInlineImage component in my site at the moment. The other components would have a similar API.
All the components can be customised with your current styling solution, for the examples I'm using Tailwind.

Hierarchy:

<UploadableInlineImage>
	<UploadableInlineImageProgressOverlay />
	<UploadableInlineImageOverlay>
		<UploadableInlineImageEditButton />
		<UploadableInlineImageDeleteButton />
	</UploadableInlineImageOverlay>
	<UploadableInlineImageDropzone>
		<UploadableInlineImageContent  />
		<UploadableInlineImageEmpty />
	</UploadableInlineImageDropzone>
</UploadableInlineImage>

Example Usage:

<UploadableInlineImage
	endpoint="updateBanner"
	// all the props like onUploadError, onClientUploadComplete, etc could be here
	imageUrl={imageUrl}
	className="h-32 w-full md:h-auto md:rounded-xl outline outline-1 -outline-offset-1 outline-zinc-950/10 bg-white"
>
	<UploadableInlineImageProgressOverlay variant="bar" />

	<UploadableInlineImageDropzone className="transition data-[drag]:opacity-50">
		<UploadableInlineImageOverlay className="group-hover:opacity-100 opacity-0 transition w-full h-full bg-foreground/60 text-background border sm:rounded-xl flex flex-col gap-2 justify-center items-center">
			<Icons.media className="opacity-50" />
			<span>Select a photo</span>
		</UploadableInlineImageOverlay>

		<UploadableInlineImageContent
			draggable={false}
			className="object-cover"
			alt="Banner"
		/>

		<UploadableInlineImageEmpty>
			<div className="w-full h-full inline-flex flex-col gap-2 justify-center items-center">
				<Icons.media className="opacity-50" />
				<span>Select a photo</span>
			</div>
		</UploadableInlineImageEmpty>
	</UploadableInlineImageDropzone>
</UploadableInlineImage>

I'm not 100% sure on UploadableInlineImageProgressOverlay as that's currently not unstyled at the moment, but I think that could be worked out easily.

Additional information

No response

👨‍👧‍👦 Contributing

• 🙋‍♂️ Yes, I'd be down to file a PR implementing this feature!

[markflorkowski]

@veloii This is definitely something we would be interested in, but internally do not have the bandwidth to build right now. If you are interested in putting together a PR, I am happy to review and provide feedback so that we can get something merged sooner!

[veloii]

Yes, I’d be happy to submit a PR, would you like a draft of the API before I start working on it?

[markflorkowski]

Yeah, that is a good idea, just to make sure we are on the same page before you put the effort into implementing.

[veloii]

Sorry for the delay - what about something like this?

Function signatures:

import React, { ElementType } from "react";
import type { ErrorMessage } from "@uploadthing/shared";
import type { FileRouter } from "uploadthing/types";

import type { UploadthingComponentProps } from "../types";
import { createUploadthing } from "uploadthing/server";

type PrimitiveComponentCallbackValues = {
  ready: boolean;
  isUploading: boolean;
  uploadProgress: number;
  fileTypes: string[];
};

type PrimitiveComponentProps<T extends ElementType = "div"> = Omit<
  React.ComponentPropsWithRef<T>,
  "children"
> & {
  children?:
  | ((values: PrimitiveComponentCallbackValues) => React.ReactNode)
  | React.ReactNode;
};

export type UploadPrimitiveProps<
  TRouter extends FileRouter,
  TEndpoint extends keyof TRouter,
  TSkipPolling extends boolean = false,
> = UploadthingComponentProps<TRouter, TEndpoint, TSkipPolling> &
  PrimitiveComponentProps;

declare function UploadPrimitive<
  TRouter extends FileRouter,
  TEndpoint extends keyof TRouter,
  TSkipPolling extends boolean = false,
>(
  props: FileRouter extends TRouter
    ? ErrorMessage<"You forgot to pass the generic">
    : UploadPrimitiveProps<TRouter, TEndpoint, TSkipPolling>,
): React.JSX.Element;

declare namespace UploadPrimitive {
  function Button(_: PrimitiveComponentProps<"button">): React.ReactNode;
  function AllowedContent(_: PrimitiveComponentProps): React.ReactNode;
  function ClearButton(_: PrimitiveComponentProps<"button">): React.ReactNode;
}

Demo:

const f = createUploadthing();

const router = {
  exampleRoute: f(["image"])
    .middleware(() => ({ foo: "bar" }))
    .onUploadComplete(({ metadata }) => {
      return { foo: "bar" as const };
    }),
};

type Router = typeof router;

function Demo() {
  return (
    <>
      <UploadPrimitive<Router, "exampleRoute">
        endpoint="exampleRoute"
        className="bg-blue-500"
      >
        <UploadPrimitive.Button className="ut-ready:bg-green-500">
          Choose Files(s)
        </UploadPrimitive.Button>

        <UploadPrimitive.ClearButton className="disabled:hidden">
          Clear files
        </UploadPrimitive.ClearButton>

        {/* Default content */}
        <UploadPrimitive.AllowedContent />

        {/* Custom content */}
        <UploadPrimitive.AllowedContent>
          {({ fileTypes }) => <div>Accepted: {fileTypes.join(", ")}</div>}
        </UploadPrimitive.AllowedContent>
      </UploadPrimitive>

      <UploadPrimitive<Router, "exampleRoute">
        endpoint="exampleRoute"
        className="bg-blue-500"
      >
        {/* get values here instead */}
        {({ fileTypes }) => (
          <>
            <UploadPrimitive.Button className="ut-ready:bg-green-500">
              Choose Files(s)
            </UploadPrimitive.Button>

            <UploadPrimitive.ClearButton className="disabled:hidden">
              Clear files
            </UploadPrimitive.ClearButton>

            <div>Accepted: {fileTypes.join(", ")}</div>
          </>
        )}
      </UploadPrimitive>
    </>
  );
}

PS: I'm aware namespace is an anti-pattern but it's the only way I can think of declaring a function on a declared function in TS

For the actual implementation, I'd just copy the current Upload button and create a context with all the PrimitiveComponentCallbackValues and have all the sub components read that.

Including @radix-ui/react-slot would allow the use of any component library (MUI, Mantine, etc) and is only 1.1kb minified+gzipped.

<UploadPrimitive.Button asChild>
  <YourComponentLibraryButton>
    Choose Files(s)
  </YourComponentLibraryButton>
</UploadPrimitive.Button>

I'm not 100% sure where this would go in the docs.

[veloii]

cc @markflorkowski

[markflorkowski]

Sorry for the delay, didn't have time over the weekend to review. Overall looks good to me, though I would probably rename the components themselves a bit:

import * as UT from ...

<UT.Root<Router, "exampleRoute">
  className="bg-blue-500"
>
  <UT.Trigger className="ut-ready:bg-green-500">
    Choose Files(s)
  </UT.Trigger>

  <UT.Clear className="disabled:hidden">
    Clear files
  </UT.Clear>

  {/* Default content */}
  <UT.AllowedContent />

  {/* Custom content */}
  <UT.AllowedContent>
    {({ fileTypes }) => <div>Accepted: {fileTypes.join(", ")}</div>}
  </UT.AllowedContent>
</UT.Root>;

I am ok with including @radix-ui/react-slot for the ergonomic win

cc @juliusmarminge -- thoughts?

As for where to put it in the docs, right now I would say as a sub-section on the theming page, but me may want to break that page into multiple, as it is already quite large 🤔

[juliusmarminge]

I like the idea of unstyled very much.

API wise I've recently found HeadlessUI's <Parent as={Button}> prop approach a bit nicer to work with than Radix's Parent asChild><Button> but that's just personal preference. (Not sure if there's a package ready-to-use for this or not but feels like it should be fairly light weight to copy props?)

Same goes for render={({ types }) => UI} prop instead of <>{({ types }) => UI}</> children render function, but again that's personal preference and at the end of the day an implementation detail

[markflorkowski]

Same goes for render={({ types }) => UI} prop instead of <>{({ types }) => UI}</> children render function, but again that's personal preference and at the end of the day an implementation detail

You prefer render={({ types }) => UI} ?

[juliusmarminge]

Yea. idk I guess just prefer not indenting stuff unnecessarily 😅

[juliusmarminge]

Another thing I think we need is for files to be a controllable prop

[dieselftw]

Is this being worked on still? Would be a HUGE win imo. I have almost the exact same use case as OP -- except I just ended up making a messy workaround.

I'm willing to drop a PR over the weekend if no one's working on this.

[juliusmarminge]

Feel free!

One thing to note though is that #886 is touching quite a bit in the component code. We'll try and get that merged before EOW so you don't have to resolve a bunch of conflicts later on