+ The Core API provides primitives for layout, navigation, theming, and data display in Console Toolkit. +
+ +{`import { Layout, Header, Sidebar } from '@storacha/console-toolkit'`}{`export default function App() {
+ return (
+
+ Content
+
+ )
+}`}Layout: children: ReactNodeHeader: actions?: ReactNodeSidebar: items?: NavItem[]+ React hooks for common patterns in Console Toolkit. +
+ +{`const [theme, setTheme] = useLocalStorage('theme', 'dark')`}{`const isLarge = useMediaQuery('(min-width: 1024px)')`}+ TypeScript interfaces used across Console Toolkit components and utilities. +
+ +{`export interface NavItem {
+ name: string
+ href?: string
+ children?: NavItem[]
+}
+
+export interface ButtonProps {
+ variant?: 'primary' | 'secondary' | 'outline'
+ size?: 'sm' | 'md' | 'lg'
+ onClick?: () => void
+}`}+ Helper utilities used across Console Toolkit for formatting, class merging, and async handling. +
+ +{`import { cn } from '@storacha/console-toolkit/utils'
+
+cn('px-2', condition && 'text-hot-blue')`}{`formatBytes(123456) // => "120.6 KB"`}+ Present information clearly with cards, tables, badges, and modals. Prefer concise summaries and + progressive disclosure. +
+ +{`
+ Title
+ Description content…
+`}{`
+
+ Name Status Job #1 Queued Job #2 Running
`}{`Queued`}+ Compose accessible forms with inputs, selects, checkboxes, and form layout helpers. Integrate with + your preferred form library. +
+ +{`
+`}{`
+`}+ Layout components provide the structural foundation for your console applications. + They handle responsive behavior, spacing, and overall page organization. +
+ +
+ The main Layout component provides the overall structure for your application,
+ including the sidebar, header, and main content area.
+
{`import { Layout } from '@storacha/console-toolkit'
+
+function App() {
+ return (
+
+ Welcome to your console
+ Your main content goes here
+
+ )
+}`}| Prop | +Type | +Default | +Description | +
|---|---|---|---|
children |
+ ReactNode |
+ - | +Content to display in the main area | +
sidebar |
+ ReactNode |
+ Default sidebar | +Custom sidebar content | +
header |
+ ReactNode |
+ Default header | +Custom header content | +
+ The Container component provides consistent max-width and padding for content sections.
+
{`import { Container } from '@storacha/console-toolkit'
+
+function ContentSection() {
+ return (
+
+ Section Title
+ This content is properly contained and centered.
+
+ )
+}`}small - Max width of 640pxmedium - Max width of 768px (default)large - Max width of 1024pxxl - Max width of 1280pxfull - Full width with padding
+ The Grid component provides a flexible grid system for laying out content.
+
{`import { Grid, GridItem } from '@storacha/console-toolkit'
+
+function Dashboard() {
+ return (
+
+
+ Metric 1
+
+
+ Metric 2
+
+
+ Metric 3
+
+
+ )
+}`}
+ The Stack component arranges children vertically or horizontally with consistent spacing.
+
{`import { Stack } from '@storacha/console-toolkit'
+
+function ButtonGroup() {
+ return (
+
+
+
+
+
+ )
+}`}| Prop | +Type | +Default | +Description | +
|---|---|---|---|
direction |
+ 'vertical' | 'horizontal' |
+ 'vertical' |
+ Stack direction | +
spacing |
+ number |
+ 4 |
+ Space between items (in rem units) | +
align |
+ 'start' | 'center' | 'end' |
+ 'start' |
+ Cross-axis alignment | +
+ All layout components are responsive by default and adapt to different screen sizes: +
+ ++++ Performance Tip: Layout components use CSS Grid and Flexbox for optimal + performance. They automatically handle responsive breakpoints without JavaScript calculations. +
+
+ Use clear and consistent navigation patterns. The docs site demonstrates a responsive sidebar, + top header, and breadcrumb patterns. +
+ +{``}{`
+
+
+`}{`Home / Components / Navigation`}nav landmarks+ Console Toolkit provides a comprehensive set of React components designed to help you build + modern console applications quickly and efficiently. All components follow Storacha's design + principles and are fully accessible. +
+ ++ {category.description} +
+All Console Toolkit components are built with the following principles in mind:
+ ++ Each component can be imported individually to keep your bundle size minimal: +
+ +{`import { Button, Card, Input } from '@storacha/console-toolkit'
+
+// Or import specific components
+import Button from '@storacha/console-toolkit/Button'
+import Card from '@storacha/console-toolkit/Card'`}+ All components come with full TypeScript support. You can import types for better + development experience: +
+ +{`import { Button, ButtonProps } from '@storacha/console-toolkit'
+
+interface MyComponentProps {
+ onSubmit: () => void
+}
+
+function MyComponent({ onSubmit }: MyComponentProps) {
+ const buttonProps: ButtonProps = {
+ variant: 'primary',
+ size: 'large',
+ onClick: onSubmit
+ }
+
+ return
+}`}+++ Pro Tip: Use your IDE's IntelliSense to explore available props and + their types. Most components also accept standard HTML attributes through prop spreading. +
+
+ Use KMS to encrypt files automatically when uploading to private spaces. Configure KMS endpoints
+ with environment variables and pass defaultEncryptionStrategy="kms".
+
+ Files will be encrypted using KMS before upload when in a private space. +
+{`# .env.local
+NEXT_PUBLIC_UCAN_KMS_URL=https://kms.storacha.network
+NEXT_PUBLIC_UCAN_KMS_DID=did:web:kms.storacha.network
+NEXT_PUBLIC_UCAN_KMS_LOCATION=us-west1
+NEXT_PUBLIC_UCAN_KMS_KEYRING=my-keyring`}+ This example demonstrates how to implement a simple file upload using the Storacha UI Toolkit. + It includes file selection, upload progress tracking, and success/error handling. +
+ ++ Try uploading a file below. You'll see real-time progress updates and receive a CID when the upload completes. +
+ ++ {file.name} +
++ {formatFileSize(file.size)} • {file.type} +
+Uploading...
+{getProgressPercentage()}%
+Upload Progress:
+ {Object.entries(uploadProgress).map(([url, progress]) => ( +Upload Successful!
+
+ CID: {dataCID.toString()}
+
Upload Failed
+{error.message}
++ Let's break down the key components and concepts used in this example: +
+ +
+ The Uploader component manages the upload state and provides context to child components:
+
{`import { Uploader } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+
+ {
+ console.log('Upload completed:', props)
+ }}>
+ {/* Upload components */}
+
+
+
+ )
+}`}
+ The useUploader hook provides access to upload state and actions:
+
{`import { useUploader } from '@storacha/ui-react'
+
+function FileUploadForm() {
+ const [{ file, status, error, dataCID, uploadProgress }] = useUploader()
+
+ // Use the state in your component
+ return (
+
+ {file && Selected: {file.name}
}
+ {status === 'uploading' && Uploading...
}
+ {status === 'succeeded' && Upload complete!
}
+ {status === 'failed' && Upload failed: {error.message}
}
+
+ )
+}`}
+ The Uploader.Input component provides a file input that integrates with the uploader:
+
{`import { Uploader } from '@storacha/ui-react'
+
+function FileInput() {
+ return (
+ + The upload process has several states that you can handle: +
+ ++ Ready for file selection. No file selected yet. +
++ File is being uploaded. Progress information is available. +
++ Upload completed successfully. CID is available. +
++ Upload failed. Error information is available. +
++ The uploader provides detailed progress information for each upload shard: +
+ +{`function ProgressDisplay() {
+ const [{ uploadProgress }] = useUploader()
+
+ return (
+
+ {Object.entries(uploadProgress).map(([url, progress]) => (
+
+ {url}
+
+
+
+ {Math.round((progress.bytesSent / progress.bytesTotal) * 100)}%
+
+ ))}
+
+ )
+}`}+ You can add client-side file validation before upload: +
+ +{`function FileUploadWithValidation() {
+ const [{ file }, { setFile }] = useUploader()
+ const [validationError, setValidationError] = useState(null)
+
+ const handleFileChange = (e) => {
+ const selectedFile = e.target.files[0]
+ setValidationError(null)
+
+ // File size validation (10MB limit)
+ if (selectedFile && selectedFile.size > 10 * 1024 * 1024) {
+ setValidationError('File size must be less than 10MB')
+ return
+ }
+
+ // File type validation
+ const allowedTypes = ['image/jpeg', 'image/png', 'image/gif']
+ if (selectedFile && !allowedTypes.includes(selectedFile.type)) {
+ setValidationError('Only JPEG, PNG, and GIF files are allowed')
+ return
+ }
+
+ setFile(selectedFile)
+ }
+
+ return (
+
+
+ {validationError && (
+ {validationError}
+ )}
+
+ )
+}`}+ Implement robust error handling for various upload scenarios: +
+ +{`function UploadWithErrorHandling() {
+ const [{ status, error }] = useUploader()
+
+ const getErrorMessage = (error) => {
+ if (error.message.includes('network')) {
+ return 'Network error. Please check your connection and try again.'
+ }
+ if (error.message.includes('size')) {
+ return 'File is too large. Please select a smaller file.'
+ }
+ if (error.message.includes('type')) {
+ return 'File type not supported. Please select a different file.'
+ }
+ return 'Upload failed. Please try again.'
+ }
+
+ return (
+
+ {status === 'failed' && error && (
+
+ Upload Failed
+ {getErrorMessage(error)}
+
+
+ )}
+
+ )
+}`}+ You can configure various upload options: +
+ +{` {
+ console.log('Upload completed:', props.dataCID)
+ }}
+>
+ {/* Upload components */}
+ `}+ Customize the appearance of upload components: +
+ +{`+ Always validate file types and sizes before upload to prevent unnecessary failures. +
+ ++ Show upload progress for files larger than a few MB to improve user experience. +
+ ++ Provide clear error messages and retry options for failed uploads. +
+ ++ Ensure upload components are accessible with proper labels and ARIA attributes. +
+ ++ Now that you understand single file uploads, you can: +
+ + + ++++ Performance Tip: For large files, consider implementing file chunking + and resumable uploads for better reliability and user experience. +
+
+ Upload multiple files or entire directories with progress tracking. This demo shows how to + collect files, visualize progress per shard, and submit the upload. +
+ +Upload Progress
+ {Object.entries(uploadProgress).map(([url, progress]) => ( +webkitdirectory attribute.uploadProgress.+ Explore live examples and integration recipes for the Storacha UI Toolkit. Each example + includes complete code, live demos, and integration patterns you can use in your own applications. +
++ {ex.description} +
++ New to the Storacha UI Toolkit? Start with these examples to understand the core concepts: +
++ This example demonstrates how to implement a complete authentication flow using the Storacha UI Toolkit. + It includes email-based authentication, account management, and session handling. +
+ ++ Try the authentication flow below. Enter your email address to sign in or create a new account. +
+ +Welcome! You are now signed in.
+Email: {accounts[0].email}
+Account ID: {accounts[0].did}
++ Let's break down the key components and concepts used in this example: +
+ +
+ The Provider component sets up the Web3.Storage client and provides context to all child components:
+
{`import { Provider } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+ {/* Your app components */}
+
+ )
+}`}
+ The Authenticator component manages authentication state and provides context to child components:
+
{`import { Authenticator } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+
+ {/* Authentication-aware components */}
+
+
+ )
+}`}
+ The useAuthenticator hook provides access to authentication state and actions:
+
{`import { useAuthenticator } from '@storacha/ui-react'
+
+function AuthForm() {
+ const [{ email, submitted, accounts }, { setEmail }] = useAuthenticator()
+
+ // Use the state and actions in your component
+ return (
+
+ )
+}`}+ The authentication flow has several states that you can handle: +
+ ++ User hasn't entered email yet. Show email input form. +
++ Form has been submitted, waiting for email verification. Show loading state. +
++ User is signed in. Show authenticated content and account information. +
++ The authentication process works as follows: +
+ ++ You can implement custom error handling for authentication failures: +
+ +{`function AuthForm() {
+ const [{ email, submitted, accounts }, { setEmail }] = useAuthenticator()
+ const [error, setError] = useState(null)
+
+ const handleSubmit = async (e) => {
+ e.preventDefault()
+ setError(null)
+
+ try {
+ // The Authenticator handles the actual authentication
+ // This is just for custom error handling
+ } catch (err) {
+ setError(err.message)
+ }
+ }
+
+ return (
+
+ )
+}`}+ The Authenticator automatically handles session persistence and restoration: +
+ ++ The Authenticator works seamlessly with other UI Toolkit components: +
+ +{`import React from 'react'
+import { Provider, Authenticator, Uploader, useW3 } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+
+
+
+
+
+
+
+
+
+ )
+}
+
+function AuthGate({ children }) {
+ const [{ accounts }] = useW3()
+
+ if (accounts.length === 0) {
+ return (
+
+ Please sign in to upload files
+ You need to be authenticated to use this feature.
+
+ )
+ }
+
+ return children
+}`}+ Always provide clear error messages and fallback states for authentication failures. +
+ ++ Show loading indicators during authentication to improve user experience. +
+ ++ Validate email format on the client side before submission. +
+ ++ Ensure your authentication forms are accessible with proper labels and ARIA attributes. +
+ ++ Now that you understand authentication, you can: +
+ + + ++++ Security Note: The authentication system uses Web3.Storage's secure + email-based authentication. Private keys are generated and stored securely in the browser. +
+
+ Ensure a space exists, display current space details, and allow users to switch or create spaces. + This example composes simple utilities into a usable flow. +
+ +Setting up space…
+ return children +} + +function SpaceInfo() { + const [{ client }] = useW3() + const [info, setInfo] = React.useState(null) + React.useEffect(() => { + if (client) { + const s = client.currentSpace() + if (s) { + setInfo({ did: s.did(), name: s.name(), isPrivate: s.meta()?.access?.type === 'private' }) + } + } + }, [client]) + if (!info) returnNo space selected
+ return ( +Name: {info.name}
+DID: {info.did}
+Type: {info.isPrivate ? 'Private' : 'Public'}
++ Display a list of uploaded files for the current space. This example shows a simple, client-side + listing pattern you can adapt to your storage/indexing approach. +
+ +Loading uploads…
+ if (error) returnError: {error}
+ + return ( +No uploads yet.
+ ) : ( + uploads.map((u, i) => ( +{u.name || 'Untitled'}
+CID: {u.cid}
+ {u.size && ( +Size: {(u.size / 1024 / 1024).toFixed(2)} MB
+ )} +client.list() call with your own indexing if needed.+ Configure Console Toolkit to match your project needs. This guide covers environment variables, + TailwindCSS integration, recommended project structure, and optional analytics/error reporting. +
+ +Add a .env.local file to configure runtime options:
{`# Example
+NEXT_PUBLIC_APP_NAME="Console Toolkit Docs"
+NEXT_PUBLIC_DEFAULT_THEME=dark
+# Analytics (optional)
+NEXT_PUBLIC_PLAUSIBLE_DOMAIN=docs.example.com
+`}Extend your Tailwind theme with Storacha colors and tokens:
+{`// tailwind.config.js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+ content: [
+ './src/**/*.{js,ts,jsx,tsx}',
+ './app/**/*.{js,ts,jsx,tsx}',
+ ],
+ darkMode: 'class',
+ theme: {
+ extend: {
+ colors: {
+ 'gray-dark': '#1d2027',
+ 'hot-red': '#E91315',
+ 'hot-red-light': '#EFE3F3',
+ 'hot-yellow': '#FFC83F',
+ 'hot-yellow-light': '#FFE4AE',
+ 'hot-blue': '#0176CE',
+ 'hot-blue-light': '#BDE0FF',
+ },
+ fontFamily: {
+ epilogue: ['Epilogue', 'sans-serif'],
+ },
+ },
+ },
+ plugins: [],
+}
+`}{`src/
+├─ app/
+│ ├─ layout.tsx # Root layout
+│ ├─ page.tsx # Home
+│ ├─ getting-started/ # Guides
+│ ├─ components/ # Docs by component area
+│ └─ styling/ # Theming and design
+└─ components/ # Reusable site UI (Layout, Sidebar, etc.)
+`}Import Tailwind layers and define prose styles used across docs:
+{`/* src/app/globals.css */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+ --hot-red: #E91315;
+ --hot-blue: #0176CE;
+}
+
+.prose h1 { @apply text-3xl font-bold mb-6; }
+.prose h2 { @apply text-2xl font-semibold mt-8 mb-4; }
+.prose p { @apply leading-relaxed text-gray-300; }
+`}NEXT_PUBLIC_PLAUSIBLE_DOMAIN and add providerThe site is compatible with static hosting (Vercel/Netlify/GitHub Pages):
+{`npm run build
+# Output is in .next/ (Vercel) or use Next export if preferred
+`}+ Console Toolkit can be installed in any React project using your preferred package manager. + This guide covers different installation methods and setup options. +
+ +npm install @storacha/console-toolkityarn add @storacha/console-toolkitpnpm add @storacha/console-toolkit+ Console Toolkit requires React 18+ and React DOM. If you don't have them installed: +
+ +npm install react@^18.0.0 react-dom@^18.0.0+ Console Toolkit is written in TypeScript and includes type definitions. No additional + @types packages are needed. +
+ ++ Console Toolkit uses TailwindCSS for styling. You'll need to install and configure + Tailwind in your project: +
+ +npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -pUpdate your tailwind.config.js:
{`/** @type {import('tailwindcss').Config} */
+module.exports = {
+ content: [
+ "./src/**/*.{js,ts,jsx,tsx,mdx}",
+ "./node_modules/@storacha/console-toolkit/**/*.{js,ts,jsx,tsx}"
+ ],
+ theme: {
+ extend: {
+ colors: {
+ 'hot-red': '#E91315',
+ 'hot-yellow': '#FFC83F',
+ 'hot-blue': '#0176CE',
+ 'gray-dark': '#1d2027',
+ },
+ },
+ },
+ plugins: [],
+}`}Add the Console Toolkit styles to your main CSS file:
+ +{`@import '@storacha/console-toolkit/dist/styles.css';
+@tailwind base;
+@tailwind components;
+@tailwind utilities;`}+ To verify the installation, create a simple test component: +
+ +{`import { Button } from '@storacha/console-toolkit'
+
+function TestComponent() {
+ return (
+
+ )
+}
+
+export default TestComponent`}+++ Next.js Users: If you're using Next.js 13+ with the app directory, + make sure to add
+'use client'directive to components that use interactive features. +
+ Get up and running with Console Toolkit in just a few minutes. This guide will walk you through + the installation process and help you create your first console application. +
+ +Install Console Toolkit using your preferred package manager:
+ +npm install @storacha/console-toolkitOr with yarn:
+ +yarn add @storacha/console-toolkitOr with pnpm:
+ +pnpm add @storacha/console-toolkit+ Once installed, you can start using Console Toolkit components in your React application. + Here's a simple example to get you started: +
+ +{`import React from 'react'
+import { Layout, Button, Card } from '@storacha/console-toolkit'
+
+function App() {
+ return (
+
+
+
+ Welcome to Console Toolkit
+
+
+
+
+ Your First Card
+
+
+ This is a simple card component styled with
+ Console Toolkit's design system.
+
+
+
+
+
+ )
+}
+
+export default App`}
+ Console Toolkit comes with built-in dark mode support. To enable theme switching,
+ wrap your application with the ThemeProvider:
+
{`import { ThemeProvider } from '@storacha/console-toolkit'
+
+function App() {
+ return (
+
+ {/* Your app content */}
+
+ )
+}`}Now that you have Console Toolkit installed and configured, you can:
+ ++++ Tip: Console Toolkit is designed to work seamlessly with existing React applications. + You can gradually adopt components as needed without requiring a complete rewrite. +
+
+ Console UI components can run in an iframe (embedded) or native (first-party) context. This guide + explains differences and how to avoid navigation context switches. +
+ ++ Follow these steps to install and initialize the Storacha Console Integration Toolkit in a React app. +
+ +{`npm install @storacha/ui-react
+# or
+yarn add @storacha/ui-react
+# or
+pnpm add @storacha/ui-react`}Add the Provider high in your tree (e.g., App.tsx):
{`import { Provider } from '@storacha/ui-react'
+
+export default function App() {
+ return (
+
+ {/* your app */}
+
+ )
+}`}{`import { Authenticator } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+
+ {/* your routes/components */}
+
+
+ )
+}`}Use your own logic or copy the pattern from examples to ensure a Space exists and is current.
+{`import { useW3 } from '@storacha/ui-react'
+import { useEffect } from 'react'
+
+function SpaceEnsurer({ children }) {
+ const [{ client }] = useW3()
+ useEffect(() => {
+ async function ensure() {
+ if (client && !client.currentSpace()) {
+ const space = client.spaces()[0] || await client.createSpace('my space')
+ await client.setCurrentSpace(space.did())
+ }
+ }
+ void ensure()
+ }, [client])
+ return <>{children}
+}`}{`import { Uploader } from '@storacha/ui-react'
+
+function UploadSection() {
+ return (
+
+
+
+
+ )
+}`}Provide KMS config via props or env. Example with Google KMS:
+{`import { Uploader } from '@storacha/ui-react'
+
+const kms = {
+ keyManagerServiceURL: process.env.NEXT_PUBLIC_UCAN_KMS_URL!,
+ keyManagerServiceDID: process.env.NEXT_PUBLIC_UCAN_KMS_DID!,
+}
+
+
+
+
+ `}{`# .env.local
+NEXT_PUBLIC_UCAN_KMS_URL=https://kms.storacha.network
+NEXT_PUBLIC_UCAN_KMS_DID=did:web:kms.storacha.network
+# optional
+NEXT_PUBLIC_UCAN_KMS_LOCATION=us-west1
+NEXT_PUBLIC_UCAN_KMS_KEYRING=my-keyring
+NEXT_PUBLIC_UCAN_KMS_ALLOW_INSECURE_HTTP=false`}+ Understanding the integration context is crucial for successfully implementing the Storacha UI Toolkit + in your application. This guide covers different integration approaches and their trade-offs. +
+ ++ There are two primary ways to integrate Storacha functionality into your application: +
+ ++ Embed Storacha functionality in an iframe within your application. +
++ Integrate Storacha components directly into your application. +
++ Use iframe integration when: +
+ ++ Use native integration when: +
+ +Configure the Storacha Provider at your app root
+Implement authentication using Authenticator components
+Ensure spaces are available for file operations
+Implement upload, download, and management features
++ The UI Toolkit provides its own state management through React context. Here's how to integrate it with your existing state management: +
+ +{`import { Provider as ReduxProvider } from 'react-redux'
+import { Provider as StorachaProvider } from '@storacha/ui-react'
+import { store } from './store'
+
+function App() {
+ return (
+
+
+ {/* Your app components */}
+
+
+ )
+}`}{`import { Provider as StorachaProvider } from '@storacha/ui-react'
+import { useStorachaStore } from './stores/storacha'
+
+function StorachaIntegration() {
+ const { setUploads, addUpload } = useStorachaStore()
+
+ return (
+
+ {
+ addUpload(props.dataCID)
+ }}>
+ {/* Upload components */}
+
+
+ )
+}`}+ Integrate Storacha components with your routing system: +
+ +{`import { BrowserRouter, Routes, Route } from 'react-router-dom'
+import { Provider as StorachaProvider } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+
+
+
+
+
+ )
+}
+
+function UploadPage() {
+ return (
+
+
+
+ {/* Upload components */}
+
+
+
+ )
+}`}{`// app/layout.tsx
+import { Provider as StorachaProvider } from '@storacha/ui-react'
+
+export default function RootLayout({
+ children,
+}: {
+ children: React.ReactNode
+}) {
+ return (
+
+
+
+ {children}
+
+
+
+ )
+}
+
+// app/upload/page.tsx
+import { Authenticator, SpaceEnsurer, Uploader } from '@storacha/ui-react'
+
+export default function UploadPage() {
+ return (
+
+
+
+ {/* Upload components */}
+
+
+
+ )
+}`}+ Integrate Storacha authentication with your existing auth system: +
+ +{`import { useAuthenticator } from '@storacha/ui-react'
+import { useAuth } from './hooks/useAuth'
+
+function AuthIntegration() {
+ const [{ accounts }] = useAuthenticator()
+ const { user, login, logout } = useAuth()
+
+ // Sync Storacha auth with your auth system
+ useEffect(() => {
+ if (accounts.length > 0 && !user) {
+ // User is authenticated with Storacha but not with your system
+ login(accounts[0].email)
+ } else if (accounts.length === 0 && user) {
+ // User is logged out of Storacha but still in your system
+ logout()
+ }
+ }, [accounts, user, login, logout])
+
+ return null // This is just for integration
+}`}+ Integrate Storacha error handling with your application's error system: +
+ +{`import { useUploader } from '@storacha/ui-react'
+import { useErrorHandler } from './hooks/useErrorHandler'
+
+function UploadWithErrorHandling() {
+ const [{ error, status }] = useUploader()
+ const { reportError } = useErrorHandler()
+
+ useEffect(() => {
+ if (error && status === 'failed') {
+ reportError({
+ type: 'STORACHA_UPLOAD_ERROR',
+ message: error.message,
+ stack: error.stack,
+ timestamp: new Date().toISOString()
+ })
+ }
+ }, [error, status, reportError])
+
+ return (
+
+ {/* Upload components */}
+
+ )
+}`}+ Implement code splitting to reduce initial bundle size: +
+ +{`import { lazy, Suspense } from 'react'
+
+const StorachaUploader = lazy(() => import('./components/StorachaUploader'))
+
+function App() {
+ return (
+ Loading...}>
+
+ )
+}`}+ Load Storacha components only when needed: +
+ +{`import { useState } from 'react'
+import { Provider as StorachaProvider } from '@storacha/ui-react'
+
+function ConditionalStorachaProvider({ children }) {
+ const [shouldLoad, setShouldLoad] = useState(false)
+
+ if (!shouldLoad) {
+ return (
+
+ )
+ }
+
+ return (
+
+ {children}
+
+ )
+}`}+ Start with simple components and gradually add more complex features as needed. +
+ ++ Wrap Storacha components in error boundaries to prevent crashes from affecting your entire app. +
+ ++ Mock Storacha components in your tests to ensure reliable test execution. +
+ ++ Monitor Storacha API usage and implement proper logging for debugging. +
+ ++ Now that you understand integration contexts, you can: +
+ ++++ Integration Tip: Start with native integration for better user experience, + and consider iframe integration only when you need complete isolation or are working with + legacy systems that are difficult to modify. +
+
+ Choosing between iframe and native integration is one of the most important decisions when + implementing Storacha functionality. This guide provides a detailed comparison to help you + make the right choice for your use case. +
+ +| Aspect | +Iframe | +Native | +
|---|---|---|
| Implementation Complexity | +Low | +Medium | +
| Performance | +Good | +Excellent | +
| User Experience | +Good | +Excellent | +
| Isolation | +Complete | +None | +
| Styling Control | +Limited | +Complete | +
| State Management | +Complex | +Simple | +
+ Iframe integration embeds Storacha functionality in a separate window context within your application. +
+ ++ Storacha code runs in a completely separate context, preventing conflicts with your application. +
++ Just embed an iframe with the Storacha application URL - no complex integration required. +
++ Clear separation between your app's styling and Storacha's styling. +
++ Storacha code cannot access your application's DOM or JavaScript context. +
++ Communication between your app and the iframe requires postMessage API, adding complexity. +
++ You need to pass authentication tokens between your app and the iframe. +
++ You cannot easily customize the appearance of Storacha components. +
++ Additional overhead from iframe context switching and message passing. +
+{`import React, { useRef, useEffect } from 'react'
+
+function StorachaIframe({ authToken, onUploadComplete }) {
+ const iframeRef = useRef(null)
+
+ useEffect(() => {
+ const handleMessage = (event) => {
+ // Verify origin for security
+ if (event.origin !== 'https://storacha.network') return
+
+ if (event.data.type === 'UPLOAD_COMPLETE') {
+ onUploadComplete(event.data.cid)
+ }
+ }
+
+ window.addEventListener('message', handleMessage)
+ return () => window.removeEventListener('message', handleMessage)
+ }, [onUploadComplete])
+
+ const handleIframeLoad = () => {
+ // Send authentication token to iframe
+ iframeRef.current?.contentWindow?.postMessage({
+ type: 'AUTH_TOKEN',
+ token: authToken
+ }, 'https://storacha.network')
+ }
+
+ return (
+
+ )
+}
+
+function App() {
+ const [authToken] = useAuth()
+
+ const handleUploadComplete = (cid) => {
+ console.log('Upload completed:', cid)
+ // Handle upload completion in your app
+ }
+
+ return (
+
+ My App
+ + Native integration embeds Storacha components directly into your application's component tree. +
+ ++ Storacha components integrate naturally with your application's routing system. +
++ Easy access to shared state between your app and Storacha components. +
++ No context switching overhead, resulting in faster user interactions. +
++ Full control over component appearance and behavior. +
++ Your application becomes more tightly coupled to Storacha's implementation. +
++ Requires integration with your application's routing and state management. +
++ Risk of CSS or JavaScript conflicts between your app and Storacha components. +
++ Storacha components add to your application's bundle size. +
+{`import React from 'react'
+import { Provider, Authenticator, SpaceEnsurer, Uploader } from '@storacha/ui-react'
+import { useAuth } from './hooks/useAuth'
+
+function StorachaUpload() {
+ const { user } = useAuth()
+
+ const handleUploadComplete = (props) => {
+ console.log('Upload completed:', props.dataCID)
+ // Update your app's state
+ updateUserUploads(props.dataCID)
+ }
+
+ return (
+
+ Upload Files
+
+
+
+
+
+
+
+ )
+}
+
+function App() {
+ return (
+
+
+
+
+
+
+ My Application
+
+
+
+
+
+
+
+
+
+ )
+}`}+ Use this decision matrix to choose the right integration approach: +
+ +| Use Case | +Recommended | +Reason | +
|---|---|---|
| Partner/Third-party Integration | +Iframe | +Complete isolation and security | +
| First-party Application | +Native | +Better UX and performance | +
| Legacy System Integration | +Iframe | +Minimal changes required | +
| Performance Critical | +Native | +No iframe overhead | +
| Quick Prototype | +Iframe | +Fastest to implement | +
| Custom Styling Required | +Native | +Full styling control | +
+ You can start with iframe integration and migrate to native integration later: +
+ ++ Start with iframe integration for quick implementation +
++ Gather user feedback and identify pain points +
++ Plan native integration based on user needs +
++ Implement native integration incrementally +
++ Now that you understand the trade-offs, you can: +
+ ++++ Recommendation: Start with native integration for first-party applications + and iframe integration for third-party integrations. You can always migrate between + approaches as your needs evolve. +
+
+ A comprehensive toolkit for building modern web console applications. + Designed with the same principles and aesthetics as Storacha's console interface. +
++ Console Toolkit provides a complete set of components, utilities, and patterns for building + professional console interfaces that match Storacha's design language. +
+{feature.description}
++ + Learn more + +
++ Jump right into the documentation sections you need most. +
++ Install Console Toolkit and start building immediately with our intuitive API. +
+
+ {`npm install @storacha/console-toolkit
+
+import { Layout, Button } from '@storacha/console-toolkit'
+
+export default function App() {
+ return (
+
+
+
+ )
+}`}
+
+ + Console Toolkit uses Storacha’s vibrant color system. Use semantic classes and keep contrast high + for readability in both dark and light contexts. +
+ +{`
+Error: Something went wrong
`}hot-blue for links and interactive elementshot-red for critical actions and error stateshot-yellow for warnings and highlights+ Console Toolkit uses a mobile-first, responsive approach with Tailwind breakpoints. Sidebars collapse, + content stacks, and grids adapt automatically. +
+ +sm: 640pxmd: 768pxlg: 1024pxxl: 1280pxmd:, lg: utilities{`
+ Card
+ Card
+ Card
+`}+ Console Toolkit features a powerful theming system that allows you to customize the look + and feel of your application while maintaining consistency with Storacha's design language. +
+ ++ The toolkit uses Storacha's signature color palette, which includes vibrant accent colors + and a carefully crafted neutral scale for optimal readability and accessibility. +
+ ++ Console Toolkit comes with built-in dark mode support. The theme automatically adapts + colors, shadows, and other visual elements for optimal viewing in low-light conditions. +
+ +{`import { ThemeProvider } from '@storacha/console-toolkit'
+
+function App() {
+ return (
+
+ {/* Your app content */}
+
+ )
+}`}+ You can easily add a theme toggle button to allow users to switch between light and dark modes: +
+ +{`import { ThemeToggle } from '@storacha/console-toolkit'
+
+function Header() {
+ return (
+
+ My App
+
+ )
+}`}+ You can create custom themes by extending the default theme configuration. This allows you + to maintain brand consistency while leveraging the toolkit's component library. +
+ +{`// theme.config.js
+const customTheme = {
+ colors: {
+ primary: {
+ 50: '#eff6ff',
+ 100: '#dbeafe',
+ // ... rest of color scale
+ 900: '#1e3a8a',
+ },
+ // Override default colors
+ 'hot-red': '#dc2626',
+ 'hot-blue': '#2563eb',
+ },
+ fontFamily: {
+ sans: ['Inter', 'system-ui', 'sans-serif'],
+ mono: ['JetBrains Mono', 'monospace'],
+ },
+ spacing: {
+ '18': '4.5rem',
+ '88': '22rem',
+ }
+}
+
+export default customTheme`}+ The theming system uses CSS custom properties (variables) for dynamic theming. This enables + smooth transitions between themes and runtime theme switching. +
+ +{`:root {
+ --color-primary: 14 165 233;
+ --color-primary-foreground: 255 255 255;
+ --color-background: 255 255 255;
+ --color-foreground: 15 23 42;
+}
+
+[data-theme="dark"] {
+ --color-primary: 59 130 246;
+ --color-primary-foreground: 15 23 42;
+ --color-background: 15 23 42;
+ --color-foreground: 248 250 252;
+}`}
+ Individual components can be customized using the className prop or by
+ creating custom variants:
+
{`// Custom button variant
+
+
+// Using CSS-in-JS
+const StyledButton = styled(Button)\`
+ background: linear-gradient(45deg, #fe6b8b 30%, #ff8e53 90%);
+ border-radius: 3px;
+ border: 0;
+ color: white;
+ height: 48px;
+ padding: 0 30px;
+\``}+++ Design Token Tip: Use the design tokens provided by the theme system + to maintain consistency across your custom components. This ensures your customizations + work well with both light and dark modes. +
+
+ Typography follows a clear hierarchy using the Epilogue font. Use the provided heading classes + and prose defaults for consistent rhythm. +
+ +{`Page Title
+Body copy with comfortable line-height.
`}{`npm run build`}Components and hooks for sign-in, session state, and auth flows.
+ +Integrations like Dmail/Web3Mail and share links.
+ +Components to discover, switch, and manage Spaces.
+ +High-level upload primitives with progress, errors, and retry.
+ +Display uploads with filters, status, and actions.
+ ++ The Authentication Suite provides a complete authentication flow for Web3.Storage, + including email-based login, account management, and session handling. It's designed + to be headless and flexible, allowing you to create custom authentication UIs. +
+ ++ The Authentication Suite consists of several components that work together: +
+ ++ Here's a simple authentication setup: +
+ +
+ The Authenticator component manages the authentication state and provides
+ context to child components.
+
+ The Authenticator provides a context with the following state and actions: +
+ +email - Current email valuesubmitted - Whether form has been submittedaccounts - Available accountsspaces - Available spacesclient - Web3.Storage client instancesetEmail - Update email valuecancelLogin - Cancel pending loginlogout - Sign out user
+ The useAuthenticator hook provides access to authentication state and actions:
+
{`import React from 'react'
+import { useAuthenticator } from '@storacha/ui-react'
+
+function AuthStatus() {
+ const [{ email, submitted, accounts }, { setEmail, logout }] = useAuthenticator()
+
+ if (accounts.length > 0) {
+ return (
+
+ Welcome! You have {accounts.length} account(s).
+
+
+ )
+ }
+
+ return (
+
+ Please sign in to continue.
+ setEmail(e.target.value)}
+ placeholder="Enter your email"
+ />
+
+ )
+}`}+ Here's a more complete authentication example with custom styling and error handling: +
+ +You are now signed in.
++ The authentication flow has several states that you can handle: +
+ ++ User hasn't entered email yet. Show email input form. +
++ Form has been submitted, waiting for email verification. Show loading state. +
++ User is signed in. Show authenticated content and account information. +
++ The authentication process works as follows: +
+ ++ The Authenticator automatically handles session persistence and restoration: +
+ ++ The Authenticator works seamlessly with other UI Toolkit components: +
+ +{`import React from 'react'
+import { Provider, Authenticator, Uploader, useW3 } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+
+
+
+
+
+
+
+
+
+ )
+}
+
+function AuthGate({ children }) {
+ const [{ accounts }] = useW3()
+
+ if (accounts.length === 0) {
+ return (
+
+ Please sign in to upload files
+ You need to be authenticated to use this feature.
+
+ )
+ }
+
+ return children
+}`}+ Always provide clear error messages and fallback states for authentication failures. +
+ ++ Show loading indicators during authentication to improve user experience. +
+ ++ Validate email format on the client side before submission. +
+ ++ Ensure your authentication forms are accessible with proper labels and ARIA attributes. +
+ ++ Now that you have authentication set up, you can: +
+ + + ++++ Security Note: The authentication system uses Web3.Storage's secure + email-based authentication. Private keys are generated and stored securely in the browser. +
+
+ The Content Management Suite provides comprehensive tools for uploading, managing, and organizing + files in Web3.Storage. It includes upload components, file listing, progress tracking, and + sharing capabilities. +
+ ++ The Content Management Suite consists of several key components: +
+ +
+ The Uploader component handles file uploads with progress tracking, error handling,
+ and support for both single files and directories.
+
+ Selected: {file.name} ({(file.size / 1024 / 1024).toFixed(2)} MB) +
+Uploading...
++ Upload successful! CID: {dataCID.toString()} +
+Upload failed: {error.message}
++ Support for uploading multiple files or entire directories: +
+ +Upload Progress
+ {Object.entries(uploadProgress).map(([url, progress]) => ( ++ For private spaces, files are automatically encrypted using KMS (Key Management Service): +
+ ++ Files will be encrypted using KMS before upload. This is automatically enabled for private spaces. +
++ The Uploader component supports various upload options: +
+ ++ Wrap single files in a directory structure +
+
+{`
+ {/* Single files will be wrapped */}
+ `}
+
+ + Upload single files as CAR (Content Addressed Archive) format +
+
+{`
+ {/* Files uploaded as CAR */}
+ `}
+
+ + Monitor upload progress with detailed status information: +
+ +{`import { useUploader } from '@storacha/ui-react'
+
+function UploadProgress() {
+ const [{ status, uploadProgress, storedDAGShards }] = useUploader()
+
+ return (
+
+
+ Upload Status: {status}
+
+
+ {status === 'uploading' && (
+
+ Progress:
+ {Object.entries(uploadProgress).map(([url, progress]) => (
+
+ {url}
+
+
+
+
+ ))}
+
+ )}
+
+ {storedDAGShards.length > 0 && (
+
+ Stored Shards: {storedDAGShards.length}
+
+ )}
+
+ )
+}`}+ Create a component to list and manage uploaded files: +
+ +Loading uploads...
+Error loading uploads: {error}
+No files uploaded yet.
+ ) : ( +{upload.name || 'Untitled'}
++ CID: {upload.cid} +
+ {upload.size && ( ++ Size: {(upload.size / 1024 / 1024).toFixed(2)} MB +
+ )} ++ Always provide clear error messages and retry options for failed uploads. +
+ ++ Show upload progress to improve user experience, especially for large files. +
+ ++ Validate file types and sizes before upload to prevent unnecessary failures. +
+ ++ Ensure a space is available before allowing uploads. +
+ ++ Content management works seamlessly with authentication and space management: +
+ +{`import React from 'react'
+import { Provider, Authenticator, Uploader, useW3 } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+
+
+
+
+
+
+
+
+
+
+ )
+}`}+ Now that you understand content management, you can: +
+ + + ++++ Performance Tip: For large files, consider implementing chunked uploads + and resumable uploads for better user experience and reliability. +
+
+ This guide will walk you through installing and setting up the Storacha Console Integration + Toolkit in your React application. The toolkit is designed to be lightweight and easy to integrate. +
+ ++ Before installing the UI Toolkit, make sure you have the following: +
+ ++ Install the main React package which includes all core components: +
+ +{`# Using npm
+npm install @storacha/ui-react
+
+# Using yarn
+yarn add @storacha/ui-react
+
+# Using pnpm
+pnpm add @storacha/ui-react`}+ For more granular control, you can install individual packages: +
+ +{`# Core functionality and types
+npm install @storacha/ui-core
+
+# Encrypted upload support (optional)
+npm install @storacha/encrypt-upload-client`}+ The UI Toolkit requires React and React DOM as peer dependencies. If you don't have them installed: +
+ +{`npm install react@^18.0.0 react-dom@^18.0.0`}+ The UI Toolkit is written in TypeScript and includes comprehensive type definitions. + No additional @types packages are needed. +
+ ++ Once installed, you can start using the UI Toolkit components. Here's a minimal setup: +
+ +{`import React from 'react'
+import { Provider, Authenticator, Uploader } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+
+
+ My Storacha App
+
+
+
+
+
+
+
+ )
+}
+
+export default App`}+ For encrypted uploads and advanced features, you may need to configure environment variables: +
+ +{`# .env.local
+NEXT_PUBLIC_UCAN_KMS_URL=https://kms.storacha.network
+NEXT_PUBLIC_UCAN_KMS_DID=did:web:kms.storacha.network
+NEXT_PUBLIC_UCAN_KMS_LOCATION=us-west1
+NEXT_PUBLIC_UCAN_KMS_KEYRING=my-keyring
+NEXT_PUBLIC_UCAN_KMS_ALLOW_INSECURE_HTTP=false`}+ The UI Toolkit components are unstyled by default, giving you complete control over appearance. + However, you can use TailwindCSS for consistent styling: +
+ +{`npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p`}
+ Update your tailwind.config.js to include Storacha's design tokens:
+
{`/** @type {import('tailwindcss').Config} */
+module.exports = {
+ content: [
+ "./src/**/*.{js,ts,jsx,tsx,mdx}",
+ "./node_modules/@storacha/ui-react/**/*.{js,ts,jsx,tsx}"
+ ],
+ theme: {
+ extend: {
+ colors: {
+ 'hot-red': '#E91315',
+ 'hot-yellow': '#FFC83F',
+ 'hot-blue': '#0176CE',
+ 'gray-dark': '#1d2027',
+ },
+ },
+ },
+ plugins: [],
+}`}+ To verify the installation is working correctly, create a simple test component: +
+ +{`import React from 'react'
+import { Provider, Authenticator } from '@storacha/ui-react'
+
+function TestComponent() {
+ return (
+
+
+
+ UI Toolkit is working!
+ If you can see this, the installation was successful.
+
+
+
+ )
+}
+
+export default TestComponent`}+ Now that you have the UI Toolkit installed, you can: +
+ ++ Make sure you're using React 16.8 or higher. The toolkit relies on React hooks + and modern React patterns. +
++ If you encounter TypeScript errors, make sure you have the latest version of + @types/react and @types/react-dom installed. +
++ If you encounter build errors, try clearing your node_modules and reinstalling + dependencies. Some bundlers may need additional configuration for ES modules. +
++ If you're still having issues: +
+ ++++ Note: The UI Toolkit is actively developed. Make sure to check for updates + regularly and review the changelog for breaking changes. +
+
+ The Storacha Console Integration Toolkit is a comprehensive React component library designed + to seamlessly integrate Storacha's Web3.Storage features into partner applications. Built + with modern React patterns and TypeScript, it provides plug-and-play components for + authentication, file management, and space operations. +
+ ++ Transform the current low-level UI package into a comprehensive UI toolkit for seamless + integration of Storacha features into partner applications, eliminating "double navigation" + UX friction and enabling native integration into host apps. +
++ {feature.description} +
++ The UI Toolkit is organized into modular packages that can be imported individually + or as a complete suite: +
+ +{`@storacha/ui-react
+├── @storacha/ui-core # Core functionality and types
+├── @storacha/ui-react # React components and hooks
+└── @storacha/encrypt-upload-client # Encrypted upload support`}{`# Install the main React package
+npm install @storacha/ui-react
+
+# Or install specific packages
+npm install @storacha/ui-core
+npm install @storacha/encrypt-upload-client`}+ {goal.description} +
++ The toolkit covers all major Storacha console features through dedicated component suites: +
+ +npm install @storacha/ui+ The UI Toolkit has minimal dependencies and is designed to work with modern React applications: +
+ ++ Ready to get started? Here's what you should do next: +
+ ++ Learn how to install and configure the UI Toolkit in your project +
++ Configure the Provider component for your application +
++ Explore working examples and integration patterns +
++++ Pro Tip: The UI Toolkit is designed to work seamlessly with existing React applications. + You can gradually adopt components as needed without requiring a complete rewrite of your application. +
+
+ The Provider component is the foundation of the Storacha UI Toolkit. It sets up
+ the Web3.Storage client, manages authentication state, and provides context to all child components.
+
+ Wrap your application with the Provider component at the root level:
+
{`import React from 'react'
+import { Provider } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+ {/* Your app content */}
+
+ )
+}
+
+export default App`}+ The Provider accepts several configuration options to customize its behavior: +
+ ++ For custom deployments or development environments, you can configure custom endpoints: +
+ +{`import React from 'react'
+import { Provider } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+ {/* Your app content */}
+
+ )
+}
+
+export default App`}+ You can use environment variables to configure different endpoints for different environments: +
+ +{`// .env.local
+NEXT_PUBLIC_WEB3_STORAGE_API_URL=https://api.web3.storage
+NEXT_PUBLIC_WEB3_STORAGE_CONNECTION_URL=https://w3s.link
+NEXT_PUBLIC_WEB3_STORAGE_RECEIPTS_URL=https://api.web3.storage/receipts`}{`import React from 'react'
+import { Provider } from '@storacha/ui-react'
+
+function App() {
+ const config = {
+ servicePrincipal: process.env.NEXT_PUBLIC_WEB3_STORAGE_API_URL,
+ connection: process.env.NEXT_PUBLIC_WEB3_STORAGE_CONNECTION_URL,
+ receiptsEndpoint: process.env.NEXT_PUBLIC_WEB3_STORAGE_RECEIPTS_URL
+ ? new URL(process.env.NEXT_PUBLIC_WEB3_STORAGE_RECEIPTS_URL)
+ : undefined
+ }
+
+ return (
+
+ {/* Your app content */}
+
+ )
+}
+
+export default App`}+ The Provider makes several hooks available to access the Web3.Storage client and state: +
+ +
+ The useW3 hook provides access to the client, accounts, and spaces:
+
{`import React from 'react'
+import { useW3 } from '@storacha/ui-react'
+
+function MyComponent() {
+ const [{ client, accounts, spaces }, { logout }] = useW3()
+
+ if (!client) {
+ return Loading...
+ }
+
+ return (
+
+ Accounts: {accounts.length}
+ Spaces: {spaces.length}
+
+
+ )
+}`}+ For encrypted uploads, you can configure KMS settings: +
+ +{`import React from 'react'
+import { useKMSConfig } from '@storacha/ui-react'
+
+function KMSConfig() {
+ const { kmsConfig, setKmsConfig, isConfigured } = useKMSConfig({
+ keyManagerServiceURL: 'https://kms.storacha.network',
+ keyManagerServiceDID: 'did:web:kms.storacha.network'
+ })
+
+ return (
+
+ KMS Configured: {isConfigured ? 'Yes' : 'No'}
+ {/* Your KMS configuration UI */}
+
+ )
+}`}+ The Provider includes built-in error handling for common scenarios: +
+ +{`import React from 'react'
+import { Provider, useW3 } from '@storacha/ui-react'
+
+function ErrorBoundary({ children }) {
+ const [{ client }] = useW3()
+
+ if (!client) {
+ return (
+
+ Connection Error
+
+ Unable to connect to Web3.Storage. Please check your network connection.
+
+
+ )
+ }
+
+ return children
+}
+
+function App() {
+ return (
+
+
+ {/* Your app content */}
+
+
+ )
+}`}+ The Provider automatically handles different environments: +
+ ++ Use only one Provider instance per application. Multiple providers can cause + state conflicts and unexpected behavior. +
+ ++ Place the Provider as high as possible in your component tree, ideally at the + root level of your application. +
+ ++ Wrap your Provider with error boundaries to handle connection failures gracefully. +
+ ++ Always check if the client is available before rendering components that depend on it. +
+ ++ Now that you have the Provider configured, you can: +
+ ++++ Tip: The Provider automatically handles client initialization and state management. + You don't need to manually manage Web3.Storage client instances. +
+
+ The Space Management Suite provides components and utilities for managing Web3.Storage spaces. + Spaces are isolated storage containers that organize your files and provide access control. + This suite handles space creation, switching, and management. +
+ ++ In Web3.Storage, spaces are the primary organizational unit for your files: +
+ +
+ The SpaceEnsurer component ensures that a space exists and is set as the current space.
+ It's essential for applications that need to guarantee a space is available.
+
Setting up space...
+Space is ready! You can now upload files.
++ You can access detailed information about the current space: +
+ +Name: {spaceInfo.name}
+DID: {spaceInfo.did}
+Type: {spaceInfo.isPrivate ? 'Private' : 'Public'}
+ {spaceInfo.meta?.description && ( +Description: {spaceInfo.meta.description}
+ )} ++ Allow users to switch between different spaces: +
+ ++ Provide functionality to create new spaces: +
+ ++ Spaces can be configured as public or private: +
+ ++ Create a custom hook for space management: +
+ +{`import { useW3 } from '@storacha/ui-react'
+import { useState, useCallback } from 'react'
+
+export function useSpaceManagement() {
+ const [{ client, spaces }] = useW3()
+ const [isLoading, setIsLoading] = useState(false)
+ const [error, setError] = useState(null)
+
+ const createSpace = useCallback(async (name) => {
+ if (!client) throw new Error('Client not available')
+
+ setIsLoading(true)
+ setError(null)
+
+ try {
+ const space = await client.createSpace(name)
+ await client.setCurrentSpace(space.did())
+ return space
+ } catch (err) {
+ setError(err.message)
+ throw err
+ } finally {
+ setIsLoading(false)
+ }
+ }, [client])
+
+ const switchSpace = useCallback(async (spaceDid) => {
+ if (!client) throw new Error('Client not available')
+
+ setIsLoading(true)
+ setError(null)
+
+ try {
+ await client.setCurrentSpace(spaceDid)
+ } catch (err) {
+ setError(err.message)
+ throw err
+ } finally {
+ setIsLoading(false)
+ }
+ }, [client])
+
+ const currentSpace = client?.currentSpace()
+
+ return {
+ spaces,
+ currentSpace,
+ createSpace,
+ switchSpace,
+ isLoading,
+ error
+ }
+}`}
+ Use SpaceEnsurer or similar logic to guarantee a space is available before
+ allowing file operations.
+
+ Provide clear error messages when space creation fails and offer retry options. +
+ ++ Always display which space is currently active to avoid user confusion. +
+ ++ Implement client-side validation for space names before creation. +
+ ++ Space management works seamlessly with upload components: +
+ +{`import React from 'react'
+import { Provider, Authenticator, Uploader, useW3 } from '@storacha/ui-react'
+
+function App() {
+ return (
+
+
+
+
+
+
+
+
+
+
+
+
+ )
+}`}+ Now that you understand space management, you can: +
+ + + ++++ Tip: Spaces are the foundation of Web3.Storage organization. + Always ensure users have a space available before attempting file operations. +
+
+ The Storacha UI Toolkit is designed to be completely unstyled by default, giving you full control + over the appearance of your components. This approach allows for seamless integration into any + design system while maintaining consistency with Storacha's design language. +
+ ++ The UI Toolkit follows these design principles: +
+ ++ The toolkit includes Storacha's signature design tokens for consistent branding: +
+ ++ Use CSS custom properties for dynamic theming: +
+ +{`:root {
+ --storacha-hot-red: #E91315;
+ --storacha-hot-red-light: #EFE3F3;
+ --storacha-hot-yellow: #FFC83F;
+ --storacha-hot-yellow-light: #FFE4AE;
+ --storacha-hot-blue: #0176CE;
+ --storacha-hot-blue-light: #BDE0FF;
+ --storacha-gray-dark: #1d2027;
+}
+
+[data-theme="dark"] {
+ --storacha-hot-red: #ff4757;
+ --storacha-hot-blue: #3742fa;
+ --storacha-hot-yellow: #ffa502;
+}`}+ The recommended approach is to use TailwindCSS with Storacha's design tokens: +
+ +{`npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p`}{`/** @type {import('tailwindcss').Config} */
+module.exports = {
+ content: [
+ "./src/**/*.{js,ts,jsx,tsx,mdx}",
+ "./node_modules/@storacha/ui-react/**/*.{js,ts,jsx,tsx}"
+ ],
+ darkMode: 'class',
+ theme: {
+ extend: {
+ colors: {
+ 'hot-red': '#E91315',
+ 'hot-red-light': '#EFE3F3',
+ 'hot-yellow': '#FFC83F',
+ 'hot-yellow-light': '#FFE4AE',
+ 'hot-blue': '#0176CE',
+ 'hot-blue-light': '#BDE0FF',
+ 'gray-dark': '#1d2027',
+ },
+ fontFamily: {
+ 'epilogue': ['Epilogue', 'sans-serif'],
+ },
+ },
+ },
+ plugins: [],
+}`}Welcome! You are signed in.
++ {file.name} +
++ {(file.size / 1024 / 1024).toFixed(2)} MB +
+Uploading...
+Upload Successful!
+
+ CID: {dataCID.toString()}
+
Upload Failed
+{error.message}
++ The UI Toolkit components work seamlessly with dark mode implementations: +
+ +{`/* TailwindCSS dark mode classes */
+.dark {
+ --storacha-bg-primary: #1f2937;
+ --storacha-bg-secondary: #374151;
+ --storacha-text-primary: #f9fafb;
+ --storacha-text-secondary: #d1d5db;
+}
+
+/* Component dark mode styles */
+.uploader-input {
+ @apply bg-white dark:bg-gray-800 text-gray-900 dark:text-white border-gray-300 dark:border-gray-600;
+}
+
+.uploader-button {
+ @apply bg-hot-blue hover:bg-hot-blue/90 text-white;
+}
+
+.uploader-progress {
+ @apply bg-blue-200 dark:bg-blue-800;
+}`}+ You can integrate with any CSS framework or use custom styles: +
+ +{`import React from 'react'
+import { Uploader, useUploader } from '@storacha/ui-react'
+
+function BootstrapUploader() {
+ const [{ file, status }] = useUploader()
+
+ return (
+
+
+
+
+ )
+}`}{`import React from 'react'
+import { Button, TextField, Box, Alert } from '@mui/material'
+import { Uploader, useUploader } from '@storacha/ui-react'
+
+function MaterialUploader() {
+ const [{ file, status, error }] = useUploader()
+
+ return (
+
+
+
+ Selected: {file.name} ({(file.size / 1024 / 1024).toFixed(2)} MB)
+
+ )}
+
+ {error && (
+
+ Upload failed: {error.message}
+
+ )}
+
+
+
+
+ )
+}`}+ Components are designed to work well on all screen sizes: +
+ +{`/* Mobile-first responsive styles */
+.uploader-container {
+ @apply w-full max-w-md mx-auto p-4;
+}
+
+@media (min-width: 768px) {
+ .uploader-container {
+ @apply max-w-2xl;
+ }
+}
+
+@media (min-width: 1024px) {
+ .uploader-container {
+ @apply max-w-4xl;
+ }
+}
+
+/* Responsive upload form */
+.upload-form {
+ @apply grid grid-cols-1 gap-4;
+}
+
+@media (min-width: 640px) {
+ .upload-form {
+ @apply grid-cols-2;
+ }
+}`}+ The UI Toolkit components include built-in accessibility features: +
+ ++ Use consistent spacing patterns throughout your application for better visual hierarchy. +
+ ++ Use Storacha's color palette consistently for branding while ensuring accessibility. +
+ ++ Maintain consistent typography scales and font weights across components. +
+ ++ Provide clear visual feedback for hover, focus, and disabled states. +
+ ++ Now that you understand theming and styling, you can: +
+ ++++ Design Tip: Start with Storacha's design tokens and customize from there. + This ensures consistency while allowing for brand-specific adaptations. +
+
+ The Uploader Components provide a comprehensive set of tools for file uploads to Web3.Storage. + These components handle everything from simple file inputs to complex multi-file uploads with + progress tracking and error handling. +
+ ++ The Uploader components follow a compound component pattern, allowing for flexible composition: +
+ +
+ The main Uploader component manages the upload state and provides context to child components.
+
+ The Uploader component manages several states: +
+ +Ready for file selection
+File is being uploaded
+Upload completed successfully
+Upload failed with error
++ Selected: {file.name} ({(file.size / 1024 / 1024).toFixed(2)} MB) +
+Uploading...
+
+ ✅ Upload successful! CID: {dataCID.toString()}
+
❌ Upload failed: {error.message}
++ Track detailed upload progress with shard information: +
+ +{file.name}
++ {(file.size / 1024 / 1024).toFixed(2)} MB • {file.type} +
+Uploading...
+{Math.round(averageProgress)}%
++ Shards stored: {storedDAGShards.length} +
+Upload Progress:
+ {Object.entries(uploadProgress).map(([url, progress]) => ( +✅ Upload Successful!
+ +❌ Upload Failed
+{error.message}
+
+ Upload entire directories with the allowDirectory prop:
+
Selected Directory ({files.length} files)
+... and {files.length - 10} more files
+ )} +Uploading directory...
+
+ ✅ Directory uploaded! CID: {dataCID.toString()}
+
❌ Upload failed: {error.message}
++ Configure upload behavior with various options: +
+ ++ Wrap single files in a directory structure for better organization +
+
+{`
+ {/* Single files will be wrapped in a directory */}
+ `}
+
+ + Upload single files as CAR (Content Addressed Archive) format +
+
+{`
+ {/* Files will be uploaded as CAR format */}
+ `}
+
+
+ Access upload state and actions with the useUploader hook:
+
+ Implement robust error handling for various upload scenarios: +
+ +{`import { useUploader } from '@storacha/ui-react'
+
+function UploadWithErrorHandling() {
+ const [{ status, error, file }] = useUploader()
+
+ const getErrorMessage = (error) => {
+ if (error.message.includes('network')) {
+ return 'Network error. Please check your connection and try again.'
+ }
+ if (error.message.includes('size')) {
+ return 'File is too large. Please select a smaller file.'
+ }
+ if (error.message.includes('type')) {
+ return 'File type not supported. Please select a different file.'
+ }
+ return 'Upload failed. Please try again.'
+ }
+
+ return (
+
+ {status === 'failed' && error && (
+
+
+
+
+
+
+ Upload Failed
+ {getErrorMessage(error)}
+
+
+
+ )}
+
+ )
+}`}+ Validate file types and sizes before upload to prevent unnecessary failures. +
+ ++ Always show upload progress for files larger than a few MB. +
+ ++ Provide clear error messages and retry options for failed uploads. +
+ ++ Ensure upload components are accessible with proper labels and ARIA attributes. +
+ ++ Now that you understand the Uploader components, you can: +
+ + + ++++ Performance Tip: For large files, consider implementing file chunking + and resumable uploads for better reliability and user experience. +
+
{initialCode}
+ )}
+ | Prop | +Type | +Default | +Description | +
|---|---|---|---|
| {r.name} | +{r.type} |
+ {r.default ?? '-'} | +{r.description} | +
Email: {account.email}
+Account ID: {account.did}
+