react-firebase-web v1.0.2
react-firebase-web ☢️🔥🕸
React Firebase components with render props
react-firebase-web provides useful set of React components with easy-to-use APIs to access most of Firebase's features.
Installation
Using npm
npm install -S react-firebase-webUsing yarn
yarn add react-firebase-webUsage
<Firebase
apiKey="AKzuSyD_O5g9322ozW28XRJ3MPgI-Q2sEBwqYmx"
projectId="react-forum-example"
>
<Value path="users/admin">{admin => <div>{admin.name}</div>}</Value>
<List path="users/test/posts" query={ref => ref.orderByKey().limitToLast(10)}>
{last10Posts => (
<ul>
{last10Posts.map(({ key, value: post }) => (
<li key={key}>{post.title}</li>
))}
</ul>
)}
</List>
<User
children={user => {
return user.uid ? <div>{user.displayName}</div> : <div />
}}
/>
<Write method="push" to="users">
{pushToUsers => <AddUser addUser={pushToUsers} />}
</Write>
</Firebase>CodeSandbox examples
These CodeSandbox examples use firebase-mock, so feel free to mess around as any change is only applied locally and reseted after reload.
- Connected, shows Firebase connection status
- Value, shows how to read and update single value
- Todos, shows to how to read and update list of values
- Populate, shows how to populate related data given a list of ids
- Login and logout, shows how to login with email & OAuth, how to log out and how to show currently logged-in user
Components
Firebase
<Firebase/> places Firebase instance to React's context, so all the other components can access it. You should wrap your app inside <Firebase/> component.
Usage
<Firebase
apiKey="your-api-key"
projectId="your-project-id"
databaseUrl="your-database-url (optional)"
firebase={yourCustomFirebaseImplementation} // optional, allows using API compatible implementation, e.g. firebase-mock for tests
>
<YourApp />
</Firebase>Connected
<Connected/> provides the current Firebase connection status as only argument for children render function.
Usage
<Connected children={connected => (connected ? "Online" : "Offline")} />List
<List/> provides given Firebase path as an array for given children render function. All array items have key and value properties. List gets re-rendered whenever there are updates to referred Firebase data.
You can provide once prop if you do not want realtime updates.
There's also query prop for limiting results, it accepts a function that gets called with Firebase reference, e.g. ref => ref.orderByKey().limitToLast(10)
Usage
<List
path="list"
children={list => (
<ul>
{list.map(({ key, value: item }) => (
<li key={key}>{item.name}</li>
))}
</ul>
)}
/>Value
<Value/> provides value of given Firebase path as an object for given children render function. Value gets re-rendered whenever there are updates to referred Firebase data.
You can provide once prop if you do not want realtime updates.
Usage
<Value path="value" children={value => <div>{value && value.name}</div>} />Populate
<Populate/> takes from prop (object with shape {key1: true, key2: true, ...}) and populates an array of related objects using with prop (function with key, key => `relatedPath/${key}`) for given children render function.
All array items have key and value properties. Populate gets re-rendered whenever there are updates to referred Firebase data.
Usage
<Populate
from={bookmarkedArticleIds}
with={articledId => `articles/${articledId}`}
children={articles => (
<ul>
{articles.map(({ key, value: article }) => (
<li key={key}>{article.title}</li>
))}
</ul>
)}
/>User
<User/> component renders given children render function with currently logged in user. Render function will receive an empty object when user is not logged in.
Usage
<User
children={user => {
if (user.uid) {
return <div>{user.displayName} Logout</div>
} else {
return <div>Login</div>
}
}}
/>OAuthLogin
<OAuthLogin/> renders given children render function with login function, which can be passed to onClick handler for example.
flow prop accepts popup and redirect as authentication flows.
provider props accepts facebook, github, google and twitter as OAuth providers.
Usage
<OAuthLogin
flow="popup"
provider="google"
children={login => <button onClick={login}>Login with Google</button>}
/>Logout
<Logout/> provides logout function for given children render function, it can then be passed to event handlers, e.g. onClick.
Usage
<Logout children={logout => <button onClick={logout}>Logout</button>} />Write
<Write/> provides mutator function for given children render function.
method prop accepts push, set, update and transaction.
to prop accepts path to mutate as a string.
Usage
<Write
method="push"
to="posts"
children={pushToPosts => {
return (
<button onClick={() => pushToPosts({ title: "Test" })}>
Push to posts
</button>
)
}}
/>EmailLogin
<EmailLogin/> logs user in using Firebase Auth's signInWithEmailAndPassword method.
Given children render function receives single parameter, a function that logs user in.
That function accepts email and password as params and returns a Promise.
Usage
<EmailLogin
children={login => (
<button onClick={() => login("test@email.dev", "password")}>Login</button>
)}
/>Registration
<Registration/> registers new user using Firebase Auth's createUserWithEmailAndPassword method.
Given children render function receives single parameter, a function that creates new user.
That function accepts email and password as params and returns a Promise.
Usage
<Registration
children={register => (
<button onClick={() => register("test@test.dev", "test")}>
Create user
</button>
)}
/>ResetPassword
<ResetPassword/> sends password reset e-mail using Firebase Auth's sendPasswordResetEmail method.
Given children render function receives single parameter, a function that sends password reset e-mail.
That function accepts email as a param and returns a Promise.
Usage
<ResetPassword
children={sendResetEmail => (
<button onClick={() => sendResetEmail("test@test.dev")}>
Send reset password e-mail
</button>
)}
/>Upload
<Upload/> is a component that uploads files to Firebase storage.
onUpload prop function is called when upload completes. It receives upload snapshot and rootRef, so you can store references to uploaded files to some other location in your Firebase database.
onComplete = (snapshot, rootRef) => {
rootRef
.child(`users/${this.props.user.uid}/uploads`)
.push(snapshot.downloadURL)
}path prop defines where uploaded files should be stored.
children render function receives an object with:
uploadFilesa function that uploads the provided files, can be used directly asreact-dropzone'sonDropcallback prop.uploadsarray of user's uploaded files.
The example below uses react-dropzone.
NOTE: Remember to enable Firebase storage in your Firebase control panel before using Upload component.
Usage
<Upload
onUpload={this.onComplete}
path="uploads"
children={({ uploadFiles, uploads }) => {
return (
<Dropzone onDrop={uploadFiles}>
{uploads.map(upload => {
const { snapshot, error, success } = upload
if (error) {
return <div>Error</div>
}
if (success) {
return <div>Success {snapshot.downloadURL}</div>
}
return <div>Uploading...</div>
})}
</Dropzone>
)
}}
/>Download
<Download/> allows you to get download url for provided Firebase Storage reference. Given children render function receives an object with url property.
If you set metadata prop as true, provided object will also include metadata object, which includes file metadata, such as contentType.
Usage
<Download
path="https://firebasestorage.googleapis.com/v0/b/example-project-sd5c9.appspot.com/o/uploads%2Factivity.svg?alt=media&token=1e39160x-fgd1-4c15-a4bf-701f12d3d754"
metadata
>
{download => (
<div>
<img src={download.url} /> {download.metadata.contentType}
</div>
)}
</Download>React Hooks
This project will be likely rewritten using hooks soon, but it will still provide current render prop components as an alternative.
Firestore
Firestore support is in progress, no ETA yet.
License
MIT