Create a Cloud Storage reference on Web

Your files are stored in aCloud Storage bucket. Thefiles in this bucket are presented in a hierarchical structure, just like thefile system on your local hard disk, or the data in theFirebase Realtime Database.By creating a reference to a file, your app gains access to it. These referencescan then be used to upload or download data, get or update metadata or deletethe file. A reference can either point to a specific file or to a higher levelnode in the hierarchy.

If you've used theFirebase Realtime Database, these paths shouldseem very familiar to you. However, your file data is stored inCloud Storage,not in theRealtime Database.

Create a Reference

In order to upload or download files, delete files, or get or update metadata,you must create a reference to the file you want to operate on. A referencecan be thought of as a pointer to a file in the cloud. References arelightweight, so you can create as many as you need, and they are also reusable formultiple operations.

To create a reference, get an instance of the Storage service usinggetStorage() then callref() with the service as an argument.This reference points to the root of yourCloud Storage bucket.

Web

import{getStorage,ref}from"firebase/storage";// Get a reference to the storage service, which is used to create references in your storage bucketconststorage=getStorage();// Create a storage reference from our storage serviceconststorageRef=ref(storage);

Web

// Get a reference to the storage service, which is used to create references in your storage bucketvarstorage=firebase.storage();// Create a storage reference from our storage servicevarstorageRef=storage.ref();

You can create a reference to a location lower in the tree,say'images/space.jpg' by passing in this path as a second argument whencallingref().

Web

import{getStorage,ref}from"firebase/storage";conststorage=getStorage();// Create a child referenceconstimagesRef=ref(storage,'images');// imagesRef now points to 'images'// Child references can also take paths delimited by '/'constspaceRef=ref(storage,'images/space.jpg');// spaceRef now points to "images/space.jpg"// imagesRef still points to "images"

Web

// Create a child referencevarimagesRef=storageRef.child('images');// imagesRef now points to 'images'// Child references can also take paths delimited by '/'varspaceRef=storageRef.child('images/space.jpg');// spaceRef now points to "images/space.jpg"// imagesRef still points to "images"

Navigate with References

You can also use theparent androot properties to navigate up thefile hierarchy.parent navigates up one level,whileroot navigates all the way to the top.

Web

import{getStorage,ref}from"firebase/storage";conststorage=getStorage();constspaceRef=ref(storage,'images/space.jpg');// Parent allows us to move to the parent of a referenceconstimagesRef=spaceRef.parent;// imagesRef now points to 'images'// Root allows us to move all the way back to the top of our bucketconstrootRef=spaceRef.root;// rootRef now points to the root

Web

// Parent allows us to move to the parent of a referencevarimagesRef=spaceRef.parent;// imagesRef now points to 'images'// Root allows us to move all the way back to the top of our bucketvarrootRef=spaceRef.root;// rootRef now points to the root

child(),parent, androot can be chained together multiple times, aseach returns a reference. The exception is theparent ofroot, whichisnull.

Web

import{getStorage,ref}from"firebase/storage";conststorage=getStorage();constspaceRef=ref(storage,'images/space.jpg');// References can be chained together multiple timesconstearthRef=ref(spaceRef.parent,'earth.jpg');// earthRef points to 'images/earth.jpg'// nullRef is null, since the parent of root is nullconstnullRef=spaceRef.root.parent;

Web

// References can be chained together multiple timesvarearthRef=spaceRef.parent.child('earth.jpg');// earthRef points to 'images/earth.jpg'// nullRef is null, since the parent of root is nullvarnullRef=spaceRef.root.parent;

Reference Properties

You can inspect references to better understand the files they point tousing thefullPath,name, andbucket properties. These propertiesget the full path of the file, the name of the file,and the bucket the file is stored in.

Web

import{getStorage,ref}from"firebase/storage";conststorage=getStorage();constspaceRef=ref(storage,'images/space.jpg');// Reference's path is: 'images/space.jpg'// This is analogous to a file path on diskspaceRef.fullPath;// Reference's name is the last segment of the full path: 'space.jpg'// This is analogous to the file namespaceRef.name;// Reference's bucket is the name of the storage bucket where files are storedspaceRef.bucket;

Web

// Reference's path is: 'images/space.jpg'// This is analogous to a file path on diskspaceRef.fullPath;// Reference's name is the last segment of the full path: 'space.jpg'// This is analogous to the file namespaceRef.name;// Reference's bucket is the name of the storage bucket where files are storedspaceRef.bucket;

Limitations on References

Reference paths and names can contain any sequence of valid Unicode characters,but certain restrictions are imposed including:

  1. Total length ofreference.fullPath must be between 1 and 1024 bytes when UTF-8 encoded.
  2. No Carriage Return or Line Feed characters.
  3. Avoid using#,[,],*, or?, as these do not work well withother tools such as theFirebase Realtime Databaseorgsutil.

Full Example

Web

import{getStorage,ref}from"firebase/storage";conststorage=getStorage();// Points to the root referenceconststorageRef=ref(storage);// Points to 'images'constimagesRef=ref(storageRef,'images');// Points to 'images/space.jpg'// Note that you can use variables to create child valuesconstfileName='space.jpg';constspaceRef=ref(imagesRef,fileName);// File path is 'images/space.jpg'constpath=spaceRef.fullPath;// File name is 'space.jpg'constname=spaceRef.name;// Points to 'images'constimagesRefAgain=spaceRef.parent;

Web

// Points to the root referencevarstorageRef=firebase.storage().ref();// Points to 'images'varimagesRef=storageRef.child('images');// Points to 'images/space.jpg'// Note that you can use variables to create child valuesvarfileName='space.jpg';varspaceRef=imagesRef.child(fileName);// File path is 'images/space.jpg'varpath=spaceRef.fullPath;// File name is 'space.jpg'varname=spaceRef.name;// Points to 'images'varimagesRef=spaceRef.parent;

Next, let's learn how toupload files toCloud Storage.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-05 UTC.