Upload

The Upload module provide a set of flexible, user-friendly interfaces for handling file uploads in your application. These components include functionalities for selecting, previewing, uploading, and managing files, with a focus on usability and customization.

Features

📂 File Upload Handling: Supports drag-and-drop and click-to-upload functionality for a seamless user experience. This is achieved using react-dropzone for handling file selection.

🖼️ Image Preview: Automatically generates previews for image files, allowing users to see their selected files before uploading.

🔄 Progress Indicators: Real-time progress indicators, provided by @start-base/start-ui, give users feedback on the status of their uploads.

🔧 Integrated with Modals: The upload process can be managed within modals using @start-base/react-modal, providing a controlled and accessible user experience.

🛠️ File Management: Includes tools for copying file URLs, downloading files, and removing files from the upload list, leveraging utilities like FileSaver for file management.

🔔 User Notifications: The Sonner library is used for displaying toast notifications, providing feedback to users during the upload process.

What's Included

< EmptyCard />

The EmptyCard component is a UI element used to display an empty state when there are no files uploaded or when a specific file-related action is loading.

`EmptyCard` Props

Name	Type	Default	Description
`title`	`string`	`null`	The title text displayed in the card.
`description`	`string`	`null`	A description text to provide more context in the card.
`action`	`ReactNode`	`null`	An optional action element (e.g., a button) displayed at the bottom.
`className`	`string`	`null`	Additional custom classes for styling the card.
`loading`	`boolean`	`false`	Indicates if a loading spinner should be displayed.

< FileCard />

The FileCard component displays information about a file, including its name, size, and a preview (if available). It also includes actions for downloading, copying URLs, and removing the file.

`FileCard` Props

Name	Type	Default	Description
`file`	`object`	`null`	The file object containing file metadata such as name and size.
`onRemove`	`function`	`null`	A function to be called when the remove action is triggered.
`onDelete`	`function`	`null`	A function to be called when the delete action is triggered.
`onShow`	`function`	`null`	A function to be called when the show action (e.g., preview) is triggered.
`progress`	`boolean`	`false`	Indicates whether a progress bar should be displayed.
`uploaded`	`boolean`	`false`	Indicates whether the file has been successfully uploaded.

< PreviewButton />

The PreviewButton component is used to trigger a preview of the selected image file in a popover. This is particularly useful for reviewing uploaded images before final submission.

`PreviewButton` Props

Name	Type	Default	Description
`file`	`string`	`null`	The URL or path to the image file to be previewed.
`label`	`string`	`null`	The label text displayed on the preview button.

< UploadButton />

The UploadButton component is the main interface for initiating file uploads. It supports multiple file types, file size limits, and integrates with the UploadZone and UploadModal components for handling the upload process.

`UploadButton` Props

Name	Type	Default	Description
`name`	`string`	`null`	The name attribute for identifying the upload button.
`label`	`string`	`null`	The label text displayed on the upload button.
`accept`	`object`	`{'image/*': []}`	Accepted file types, following the input accept attribute specification.
`setFiles`	`function`	`null`	A function to update the file list after files are selected.
`value`	`object`	`null`	The current file(s) selected.
`maxSize`	`number`	`4`	The maximum file size allowed for upload, in MB.
`maxFiles`	`number`	`1`	The maximum number of files that can be uploaded.
`disabled`	`boolean`	`false`	Disables the upload button when set to true.
`preview`	`string`	`null`	A URL to an image for previewing the currently selected file.
`error`	`object`	`null`	An error object containing error messages related to file upload.

< UploadModal />

The UploadModal component wraps the UploadZone component within a modal, allowing users to manage file uploads in a focused, isolated UI.

`UploadModal` Props

Name	Type	Default	Description
`isModalOpen`	`boolean`	`false`	Controls the visibility of the modal.
`label`	`string`	`null`	The label text displayed in the modal header.
`setIsModalOpen`	`function`	`null`	A function to toggle the modal's open state.
`setFiles`	`function`	`null`	A function to update the file list after files are selected.
`value`	`object`	`null`	The current file(s) selected.
`accept`	`object`	`{'image/*': []}`	Accepted file types for upload.
`maxFiles`	`number`	`1`	The maximum number of files that can be uploaded.
`maxSize`	`number`	`4`	The maximum file size allowed for upload, in MB.

< Uploaded />

The Uploaded component displays a list of files that have already been uploaded. It includes functionality to view, delete, or download files.

`Uploaded` Props

Name	Type	Default	Description
`bucket`	`string`	`null`	The storage bucket from which to fetch and manage uploaded files.

< UploadZone />

The UploadZone component provides the drag-and-drop area for file uploads. It supports multiple file types, file size limits, and real-time upload progress.

`UploadZone` Props

Name	Type	Default	Description
`value`	`object`	`null`	The current file(s) selected.
`onValueChange`	`function`	`null`	A function to update the file list after files are selected.
`name`	`string`	`null`	The name attribute for identifying the upload zone.
`label`	`string`	`null`	The label text displayed in the upload zone.
`bucket`	`string`	`null`	The storage bucket used for file uploads.
`onUpload`	`function`	`null`	A function to handle the file upload process.
`accept`	`object`	`{'image/*': []}`	Accepted file types for upload.
`maxSize`	`number`	`4`	The maximum file size allowed for upload, in MB.
`maxFiles`	`number`	`Infinity`	The maximum number of files that can be uploaded.
`disabled`	`boolean`	`false`	Disables the upload zone when set to true.
`className`	`string`	`null`	Additional custom classes for styling the upload zone.
`hidden`	`boolean`	`false`	Hides the upload zone when set to true.
`error`	`object`	`null`	An error object containing error messages related to file upload.

Individual Use Cases

These components can be used individually in different sections of your application, such as the files section on the admin panel or within forms using React Hook Form. You can easily integrate them into existing forms or other parts of the UI by importing the necessary components and passing the required props.

Setup Component's Needs

Configure Environment Variables

Sign Up or Log In to Supabase: Go to Supabase and sign up or log in.
Create a New Supabase Project: In the Supabase dashboard, create a new project. You'll receive an API URL and an API Key for your project.
Supabase Storage Buckets: Create a storage bucket in your Supabase project.
Configure Environment Variables: In the root of your Next.js project, create or update your .env.local file. Add the following environment variables and replace the placeholders with your actual Supabase details:

NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
NEXT_PUBLIC_FILE_SUPABASE_BUCKET=your-bucket-name

Set Up Row Level Security (RLS): Use Supabase's Row Level Security (RLS) policies to restrict access to certain data based on user roles. This can be configured directly in the Supabase dashboard under your project's settings. Ensure your bucket is public.