Module 4
Topic 4
Storage
Managing file uploads, downloads, and media storage with Supabase Storage buckets.
Supabase Storage Overview
Supabase Storage provides a scalable file storage solution for your Flutter apps. It's built on top of Amazon S3 and offers:
- Public & Private Buckets – Control who can access your files
- Image Optimization – Automatic resizing and optimization
- CDN Delivery – Fast global content delivery
- File Management – Upload, download, delete, and list files
- Security – Row Level Security policies for storage
Public Buckets
Anyone can read files. Good for profile pictures, public assets
Private Buckets
Only authenticated users with proper permissions can access
✅ Storage Use Cases
- Profile Pictures – User avatars uploaded to a public bucket
- Post Images – Images for posts or articles
- Video Uploads – User-generated video content
- Documents – PDFs, spreadsheets, and other documents
- Chat Media – Images and files in chat messages
Setting Up Storage
To use storage in your Flutter app, you need to create a bucket and set up the proper policies.
SQL – Create Storage Buckets
-- Create a public bucket for avatars
INSERT INTO storage.buckets (id, name, public)
VALUES ('avatars', 'avatars', true);
-- Create a private bucket for user documents
INSERT INTO storage.buckets (id, name, public)
VALUES ('documents', 'documents', false);
-- Policy: Allow users to upload their own avatar
CREATE POLICY "Users can upload their own avatar"
ON storage.objects
FOR INSERT
TO authenticated
WITH CHECK (
bucket_id = 'avatars' AND
(storage.foldername(name))[1] = auth.uid()::text
);
-- Policy: Allow users to read any avatar
CREATE POLICY "Anyone can read avatars"
ON storage.objects
FOR SELECT
USING (bucket_id = 'avatars');
Uploading Files
Uploading files to Supabase Storage is done through the
storage
API.
lib/services/storage_service.dart – Upload File
import
'dart:io'
;
import
'package:supabase_flutter/supabase_flutter.dart'
;
import
'package:image_picker/image_picker.dart'
;
class
StorageService
{
final
SupabaseClient client = Supabase.instance.client;
// Upload an image file
Future
<String?>
uploadAvatar
({
required
String userId,
required
XFile file,
}) async {
try
{
// Convert XFile to File
final
File imageFile = File(file.path);
final
bytes =
await
imageFile.readAsBytes();
// Generate a unique file name
final
timestamp = DateTime.now().millisecondsSinceEpoch;
final
filePath =
'$userId/avatar_$timestamp.jpg'
;
// Upload to the avatars bucket
final
response =
await
client.storage
.from(
'avatars'
)
.uploadBinary(
filePath,
bytes,
fileOptions: FileOptions(
cacheControl:
'3600'
,
upsert:
true
,
contentType:
'image/jpeg'
,
),
);
// Get the public URL
final
publicUrl = client.storage
.from(
'avatars'
)
.getPublicUrl(filePath);
return
publicUrl;
}
catch
(e) {
print(
'Upload failed: $e'
);
return
null
;
}
}
// Upload a post image
Future
<String?>
uploadPostImage
({
required
String postId,
required
XFile file,
}) async {
try
{
final
File imageFile = File(file.path);
final
bytes =
await
imageFile.readAsBytes();
final
timestamp = DateTime.now().millisecondsSinceEpoch;
final
filePath =
'posts/$postId/image_$timestamp.jpg'
;
final
response =
await
client.storage
.from(
'posts'
)
.uploadBinary(filePath, bytes);
final
publicUrl = client.storage
.from(
'posts'
)
.getPublicUrl(filePath);
return
publicUrl;
}
catch
(e) {
print(
'Upload failed: $e'
);
return
null
;
}
}
}
lib/screens/profile_screen.dart – Upload UI
class
ProfileScreen
extends
StatefulWidget {
@override
State<ProfileScreen>
createState
() => _ProfileScreenState();
}
class
_ProfileScreenState
extends
State<ProfileScreen> {
final
StorageService _storageService = StorageService();
final
ImagePicker _picker = ImagePicker();
String? _avatarUrl;
bool
_isUploading =
false
;
Future
<
void
>
_pickImage
() async {
final
XFile? image =
await
_picker.pickImage(
source: ImageSource.gallery,
maxWidth:
512
,
maxHeight:
512
,
imageQuality:
80
,
);
if
(image !=
null
) {
await
_uploadImage(image);
}
}
Future
<
void
>
_uploadImage
(XFile image) async {
setState(() => _isUploading =
true
);
final
user = Supabase.instance.client.auth.currentUser;
if
(user ==
null
)
return
;
final
url =
await
_storageService.uploadAvatar(
userId: user.id,
file: image,
);
if
(url !=
null
) {
setState(() {
_avatarUrl = url;
_isUploading =
false
;
});
}
else
{
setState(() => _isUploading =
false
);
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(
content: Text(
'Upload failed'
),
backgroundColor: Colors.red,
),
);
}
}
@override
Widget
build
(BuildContext context) {
return
Scaffold(
appBar: AppBar(
title: Text(
'Profile'
),
centerTitle:
true
,
),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
// Avatar
Stack(
children: [
CircleAvatar(
radius:
50
,
backgroundColor: Colors.grey.shade200,
backgroundImage: _avatarUrl !=
null
? NetworkImage(_avatarUrl!)
:
null
,
child: _avatarUrl ==
null
? Icon(Icons.person, size:
50
, color: Colors.grey.shade400)
:
null
,
),
if
(_isUploading)
Positioned.fill(
child: Container(
decoration: BoxDecoration(
color: Colors.black.withOpacity(
0.5
),
shape: BoxShape.circle,
),
child: Center(
child: CircularProgressIndicator(
color: Colors.white,
),
),
),
),
Positioned(
bottom:
0
,
right:
0
,
child: CircleAvatar(
radius:
16
,
backgroundColor: Colors.deepPurple,
child: IconButton(
icon: Icon(Icons.camera_alt, size:
16
, color: Colors.white),
padding: EdgeInsets.zero,
onPressed: _pickImage,
),
),
),
],
),
SizedBox(height:
16
),
Text(
'Tap the camera icon to upload a profile picture'
,
style: TextStyle(color: Colors.grey.shade600),
textAlign: TextAlign.center,
),
],
),
),
);
}
}
Downloading Files
There are two ways to access files from Supabase Storage: public URLs and signed URLs.
lib/services/download_service.dart – Download Files
class
DownloadService
{
final
SupabaseClient client = Supabase.instance.client;
// Get public URL (for public buckets)
String
getPublicUrl
(String bucket, String path) {
return
client.storage.from(bucket).getPublicUrl(path);
}
// Get signed URL (for private buckets, expires after 60 seconds)
Future
<String?>
getSignedUrl
({
required
String bucket,
required
String path,
int
expiresIn =
60
,
}) async {
try
{
final
response =
await
client.storage
.from(bucket)
.createSignedUrl(path, expiresIn);
return
response;
}
catch
(e) {
print(
'Error getting signed URL: $e'
);
return
null
;
}
}
// Download file as bytes
Future
<List<int>?>
downloadFile
({
required
String bucket,
required
String path,
}) async {
try
{
final
response =
await
client.storage
.from(bucket)
.download(path);
return
response;
}
catch
(e) {
print(
'Error downloading file: $e'
);
return
null
;
}
}
// Get file information
Future
<Map<String, dynamic>?>
getFileInfo
({
required
String bucket,
required
String path,
}) async {
try
{
final
response =
await
client.storage
.from(bucket)
.info(path);
return
response;
}
catch
(e) {
print(
'Error getting file info: $e'
);
return
null
;
}
}
}
🔑 Public vs Signed URLs
- Public URLs – Anyone can access. Use for public buckets (avatars, logos, etc.)
- Signed URLs – Temporary access. Use for private buckets (user documents, etc.)
- Signed URLs expire – Default is 60 seconds, can be customized
Listing and Managing Files
You can list, move, copy, and delete files in Supabase Storage.
lib/services/storage_manager.dart – File Management
class
StorageManager
{
final
SupabaseClient client = Supabase.instance.client;
// List files in a folder
Future
<List<Map<String, dynamic>>>
listFiles
({
required
String bucket,
String? path,
int
? limit,
String? offset,
}) async {
try
{
final
response =
await
client.storage
.from(bucket)
.list(path ??
''
, options: ListOptions(
limit: limit,
offset: offset,
sortBy:
'created_at'
,
));
return
response;
}
catch
(e) {
print(
'Error listing files: $e'
);
return
[];
}
}
// Move a file
Future
<
bool
>
moveFile
({
required
String bucket,
required
String fromPath,
required
String toPath,
}) async {
try
{
await
client.storage
.from(bucket)
.move(fromPath, toPath);
return
true
;
}
catch
(e) {
print(
'Error moving file: $e'
);
return
false
;
}
}
// Copy a file
Future
<
bool
>
copyFile
({
required
String bucket,
required
String fromPath,
required
String toPath,
}) async {
try
{
await
client.storage
.from(bucket)
.copy(fromPath, toPath);
return
true
;
}
catch
(e) {
print(
'Error copying file: $e'
);
return
false
;
}
}
// Delete a file
Future
<
bool
>
deleteFile
({
required
String bucket,
required
String path,
}) async {
try
{
await
client.storage
.from(bucket)
.remove([path]);
return
true
;
}
catch
(e) {
print(
'Error deleting file: $e'
);
return
false
;
}
}
// Delete multiple files
Future
<
bool
>
deleteMultipleFiles
({
required
String bucket,
required
List<String> paths,
}) async {
try
{
await
client.storage
.from(bucket)
.remove(paths);
return
true
;
}
catch
(e) {
print(
'Error deleting files: $e'
);
return
false
;
}
}
}
Complete Example: Image Gallery App
Here's a complete image gallery app using Supabase Storage.
lib/main.dart – Complete Gallery App
import
'dart:io'
;
import
'package:flutter/material.dart'
;
import
'package:supabase_flutter/supabase_flutter.dart'
;
import
'package:image_picker/image_picker.dart'
;
import
'package:cached_network_image/cached_network_image.dart'
;
void
main
() async {
await
Supabase.initialize(
url:
'https://your-project.supabase.co'
,
anonKey:
'your-anon-key'
,
);
runApp(
MyApp
());
}
class
MyApp
extends
StatelessWidget {
@override
Widget
build
(BuildContext context) {
return
MaterialApp(
title:
'Image Gallery'
,
theme: ThemeData(
colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
useMaterial3:
true
,
),
home: GalleryScreen(),
);
}
}
// ==========================================
// 1. STORAGE SERVICE
// ==========================================
class
GalleryStorageService
{
final
SupabaseClient client = Supabase.instance.client;
Future
<String?>
uploadImage
({
required
XFile file,
required
String userId,
}) async {
try
{
final
bytes =
await
File(file.path).readAsBytes();
final
timestamp = DateTime.now().millisecondsSinceEpoch;
final
path =
'$userId/gallery_$timestamp.jpg'
;
await
client.storage
.from(
'gallery'
)
.uploadBinary(path, bytes);
return
client.storage
.from(
'gallery'
)
.getPublicUrl(path);
}
catch
(e) {
print(
'Upload failed: $e'
);
return
null
;
}
}
Future
<List<Map<String, dynamic>>>
listImages
(String userId) async {
try
{
return
await
client.storage
.from(
'gallery'
)
.list(userId);
}
catch
(e) {
print(
'List failed: $e'
);
return
[];
}
}
Future
<
bool
>
deleteImage
(String path) async {
try
{
await
client.storage
.from(
'gallery'
)
.remove([path]);
return
true
;
}
catch
(e) {
print(
'Delete failed: $e'
);
return
false
;
}
}
String
getPublicUrl
(String path) {
return
client.storage.from(
'gallery'
).getPublicUrl(path);
}
}
// ==========================================
// 2. GALLERY SCREEN
// ==========================================
class
GalleryScreen
extends
StatefulWidget {
@override
State<GalleryScreen>
createState
() => _GalleryScreenState();
}
class
_GalleryScreenState
extends
State<GalleryScreen> {
final
GalleryStorageService _storageService = GalleryStorageService();
final
ImagePicker _picker = ImagePicker();
List<Map<String, dynamic>> _images = [];
bool
_isLoading =
true
;
bool
_isUploading =
false
;
String? _userId;
@override
void
initState
() {
super
.initState();
_userId = Supabase.instance.client.auth.currentSession?.user.id;
if
(_userId !=
null
) {
_loadImages();
}
}
Future
<
void
>
_loadImages
() async {
setState(() => _isLoading =
true
);
final
images =
await
_storageService.listImages(_userId!);
setState(() {
_images = images;
_isLoading =
false
;
});
}
Future
<
void
>
_pickAndUpload
() async {
final
XFile? image =
await
_picker.pickImage(
source: ImageSource.gallery,
maxWidth:
1024
,
maxHeight:
1024
,
imageQuality:
80
,
);
if
(image ==
null
|| _userId ==
null
)
return
;
setState(() => _isUploading =
true
);
final
url =
await
_storageService.uploadImage(
file: image,
userId: _userId!,
);
setState(() => _isUploading =
false
);
if
(url !=
null
) {
await
_loadImages();
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text(
'Image uploaded!'
), backgroundColor: Colors.green),
);
}
else
{
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text(
'Upload failed'
), backgroundColor: Colors.red),
);
}
}
Future
<
void
>
_deleteImage
(String path) async {
setState(() => _isLoading =
true
);
final
success =
await
_storageService.deleteImage(path);
setState(() => _isLoading =
false
);
if
(success) {
await
_loadImages();
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text(
'Image deleted'
)),
);
}
}
@override
Widget
build
(BuildContext context) {
return
Scaffold(
appBar: AppBar(
title: Text(
'🖼️ Gallery'
),
centerTitle:
true
,
actions: [
IconButton(
icon: Icon(Icons.refresh),
onPressed: _loadImages,
),
],
),
body: _isLoading
? Center(child: CircularProgressIndicator())
: _images.isEmpty
? Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(Icons.photo_library, size:
80
, color: Colors.grey.shade400),
SizedBox(height:
16
),
Text(
'No images yet'
,
style: TextStyle(fontSize:
20
, fontWeight: FontWeight.w600),
),
Text(
'Tap the + button to upload one'
,
style: TextStyle(color: Colors.grey.shade400),
),
],
),
)
: GridView.builder(
padding: EdgeInsets.all(
8
),
gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
crossAxisCount:
3
,
crossAxisSpacing:
4
,
mainAxisSpacing:
4
,
),
itemCount: _images.length,
itemBuilder: (context, index) {
final
image = _images[index];
final
path = image[
'name'
]
as
String;
final
fullPath =
'$_userId/$path'
;
final
url = _storageService.getPublicUrl(fullPath);
return
Stack(
children: [
GestureDetector(
onTap: () {
showDialog(
context: context,
builder: (context) => Dialog(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
ClipRRect(
borderRadius: BorderRadius.circular(
8
),
child: CachedNetworkImage(
imageUrl: url,
fit: BoxFit.cover,
placeholder: (context, url) => Container(
height:
300
,
child: Center(
child: CircularProgressIndicator(),
),
),
errorWidget: (context, url, error) => Container(
height:
300
,
color: Colors.grey.shade200,
child: Icon(Icons.error, color: Colors.red),
),
),
),
Padding(
padding: EdgeInsets.all(
8
),
child: ElevatedButton.icon(
icon: Icon(Icons.delete, color: Colors.red),
label: Text(
'Delete'
),
onPressed: () {
Navigator.pop(context);
_deleteImage(fullPath);
},
style: ElevatedButton.styleFrom(
backgroundColor: Colors.red.shade50,
foregroundColor: Colors.red,
),
),
),
],
),
),
);
},
child: Container(
decoration: BoxDecoration(
color: Colors.grey.shade100,
borderRadius: BorderRadius.circular(
4
),
),
child: ClipRRect(
borderRadius: BorderRadius.circular(
4
),
child: CachedNetworkImage(
imageUrl: url,
fit: BoxFit.cover,
placeholder: (context, url) => Center(
child: CircularProgressIndicator(),
),
errorWidget: (context, url, error) => Icon(
Icons.broken_image,
color: Colors.grey.shade400,
),
),
),
),
),
],
);
},
),
floatingActionButton: _isUploading
? FloatingActionButton(
onPressed:
null
,
child: CircularProgressIndicator(
color: Colors.white,
strokeWidth:
2
,
),
)
: FloatingActionButton(
onPressed: _pickAndUpload,
child: Icon(Icons.add),
),
);
}
}
Step-by-Step Explanation
1.
Create a bucket
– Use the SQL Editor or Supabase Dashboard to create public or private buckets.
2.
Set up policies
– Create RLS policies to control who can upload, read, and delete files.
3.
Upload files
– Use
storage.from(bucket).uploadBinary()
to upload files.
4.
Get URLs
– Use
getPublicUrl()
for public buckets or
createSignedUrl()
for private buckets.
5.
Display images
– Use
CachedNetworkImage
for efficient image loading with caching.
Common Mistakes
❌ Mistake 1: Not setting up storage policies
Without proper policies, users won't be able to upload or access files, even if the bucket is public.
✅ Correct: Always set up RLS policies
Create policies for INSERT, SELECT, DELETE operations on the
storage.objects
table.
❌ Mistake 2: Using public URLs for private buckets
Public URLs only work for public buckets. For private buckets, you need signed URLs.
✅ Correct: Use signed URLs for private buckets
Use
createSignedUrl()
to get temporary access to private files.
❌ Mistake 3: Not handling upload errors
Uploads can fail for many reasons (network issues, file size limits, etc.). Always handle errors gracefully.
✅ Correct: Always handle upload errors
Use try-catch blocks and show user-friendly error messages when uploads fail.
🎯 Key Takeaway
Supabase Storage provides scalable file storage with public and private buckets. Use public URLs for public assets and signed URLs for private files. Always set up RLS policies for security and use CachedNetworkImage for efficient image display. Storage makes media management simple and secure.