Overview

CLI tool

SDKs

Project setup and initialization

Auth Overview

Email-Password accounts

Identity Providers

Anonymous accounts

Manage users

Firestore

Collection

Document

Query

Create and update documents

Batch writes

Transactions

Timestamp value type (advanced)

Firestore Security rules

Storage

File references and metadata

List files and folders

Read, download files

Upload data

Setting the bucket CORS header

Cloud Functions

Define Callable functions

Invoke Callable functions

HTTP functions

Run functions on Auth events

on Firestore and Storage events

Dates and Timestamps serialization

Environment variables

Debug Functions locally

Schedule Cron jobs

# Overview

<div class="bookHeroImage" style="padding: 32px;margin: 8px 0;">
<svg viewBox="0 0 749 205" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M707.39 161.434C700.156 161.434 693.615 159.749 687.768 156.379C682.021 153.01 677.512 148.352 674.241 142.406C670.971 136.361 669.336 129.623 669.336 122.19C669.336 115.055 670.872 108.514 673.944 102.568C677.115 96.5234 681.525 91.7666 687.174 88.2981C692.822 84.7306 699.264 82.9468 706.498 82.9468C713.931 82.9468 720.372 84.5819 725.823 87.8522C731.372 91.1225 735.584 95.6811 738.458 101.528C741.332 107.276 742.769 113.915 742.769 121.447C742.769 122.339 742.719 123.231 742.62 124.123C742.521 125.014 742.471 125.51 742.471 125.609H685.687C686.183 132.348 688.611 137.551 692.971 141.217C697.332 144.884 702.286 146.717 707.836 146.717C716.359 146.717 722.899 142.753 727.458 134.825L741.431 141.515C738.16 147.56 733.602 152.415 727.755 156.082C722.007 159.65 715.219 161.434 707.39 161.434ZM726.12 113.123C725.922 110.744 725.129 108.316 723.742 105.839C722.354 103.361 720.174 101.28 717.201 99.5955C714.327 97.8117 710.71 96.9198 706.35 96.9198C701.494 96.9198 697.282 98.4063 693.714 101.379C690.246 104.352 687.868 108.267 686.579 113.123H726.12Z" fill="#5E5E5E"/>
<path d="M633.449 161.434C625.025 161.434 618.039 159.501 612.489 155.636C607.039 151.672 603.174 146.717 600.895 140.771L615.462 134.528C617.147 138.591 619.575 141.663 622.746 143.744C626.016 145.825 629.584 146.866 633.449 146.866C637.512 146.866 640.832 146.123 643.408 144.636C645.985 143.051 647.273 141.019 647.273 138.542C647.273 136.163 646.233 134.231 644.151 132.744C642.07 131.159 638.651 129.771 633.895 128.582L623.786 126.204C618.237 124.915 613.431 122.537 609.368 119.069C605.404 115.501 603.422 110.893 603.422 105.244C603.422 98.4063 606.246 93.0054 611.895 89.0414C617.543 84.9783 624.48 82.9468 632.705 82.9468C639.543 82.9468 645.588 84.3837 650.841 87.2576C656.192 90.1315 660.057 94.2937 662.435 99.7441L648.016 105.839C646.629 102.767 644.498 100.487 641.624 99.0009C638.75 97.5144 635.629 96.7711 632.26 96.7711C628.989 96.7711 626.115 97.5144 623.638 99.0009C621.16 100.388 619.922 102.271 619.922 104.65C619.922 106.731 620.764 108.415 622.449 109.704C624.232 110.992 627.007 112.082 630.773 112.974L641.773 115.65C649.205 117.532 654.755 120.406 658.422 124.271C662.088 128.037 663.922 132.596 663.922 137.947C663.922 142.307 662.584 146.271 659.908 149.839C657.332 153.406 653.715 156.231 649.057 158.312C644.498 160.393 639.296 161.434 633.449 161.434Z" fill="#5E5E5E"/>
<path d="M555.223 161.434C549.971 161.434 545.214 160.393 540.953 158.312C536.791 156.132 533.471 153.159 530.993 149.393C528.615 145.528 527.426 141.168 527.426 136.312C527.426 128.582 530.3 122.487 536.047 118.028C541.894 113.568 549.277 111.339 558.196 111.339C566.025 111.339 572.714 112.677 578.264 115.352V112.231C578.264 107.771 576.48 104.105 572.912 101.231C569.444 98.2576 565.232 96.7711 560.277 96.7711C552.746 96.7711 546.701 99.8432 542.142 105.987L529.656 97.3657C533.124 92.7081 537.435 89.1405 542.588 86.663C547.84 84.1855 553.737 82.9468 560.277 82.9468C571.079 82.9468 579.403 85.672 585.25 91.1225C591.196 96.4738 594.169 104.055 594.169 113.866V159.055H578.264V149.988H577.372C574.994 153.357 571.971 156.132 568.304 158.312C564.638 160.393 560.277 161.434 555.223 161.434ZM557.899 147.906C561.566 147.906 564.935 147.015 568.007 145.231C571.178 143.348 573.656 140.92 575.439 137.947C577.322 134.875 578.264 131.605 578.264 128.136C573.012 125.262 567.412 123.825 561.466 123.825C556.016 123.825 551.755 125.014 548.683 127.393C545.611 129.771 544.075 132.794 544.075 136.46C544.075 139.83 545.412 142.605 548.088 144.785C550.863 146.866 554.133 147.906 557.899 147.906Z" fill="#5E5E5E"/>
<path d="M486.618 161.433C481.266 161.433 476.46 160.294 472.199 158.014C468.037 155.735 464.915 152.861 462.834 149.393H461.942V159.055H446.482V52.6221H462.834V84.5816L461.942 94.8384H462.834C464.915 91.469 468.037 88.6447 472.199 86.3654C476.46 84.0861 481.266 82.9465 486.618 82.9465C492.96 82.9465 498.807 84.6312 504.158 88.0006C509.609 91.3699 513.92 96.0772 517.091 102.122C520.361 108.068 521.996 114.757 521.996 122.19C521.996 129.622 520.361 136.312 517.091 142.257C513.92 148.203 509.609 152.911 504.158 156.379C498.807 159.749 492.96 161.433 486.618 161.433ZM483.793 146.42C487.658 146.42 491.226 145.429 494.496 143.447C497.865 141.465 500.541 138.64 502.523 134.974C504.604 131.208 505.645 126.947 505.645 122.19C505.645 117.433 504.604 113.221 502.523 109.555C500.541 105.789 497.865 102.915 494.496 100.933C491.226 98.951 487.658 97.9601 483.793 97.9601C479.928 97.9601 476.311 98.951 472.942 100.933C469.672 102.915 466.996 105.739 464.915 109.406C462.933 113.073 461.942 117.334 461.942 122.19C461.942 127.046 462.933 131.307 464.915 134.974C466.996 138.64 469.672 141.465 472.942 143.447C476.311 145.429 479.928 146.42 483.793 146.42Z" fill="#5E5E5E"/>
<path d="M401.365 161.434C394.13 161.434 387.59 159.749 381.743 156.379C375.995 153.01 371.486 148.352 368.216 142.406C364.946 136.361 363.311 129.623 363.311 122.19C363.311 115.055 364.847 108.514 367.919 102.568C371.09 96.5234 375.5 91.7666 381.148 88.2981C386.797 84.7306 393.239 82.9468 400.473 82.9468C407.905 82.9468 414.347 84.5819 419.797 87.8522C425.347 91.1225 429.559 95.6811 432.432 101.528C435.306 107.276 436.743 113.915 436.743 121.447C436.743 122.339 436.694 123.231 436.595 124.123C436.495 125.014 436.446 125.51 436.446 125.609H379.662C380.157 132.348 382.585 137.551 386.946 141.217C391.306 144.884 396.261 146.717 401.811 146.717C410.333 146.717 416.874 142.753 421.432 134.825L435.405 141.515C432.135 147.56 427.577 152.415 421.73 156.082C415.982 159.65 409.194 161.434 401.365 161.434ZM420.095 113.123C419.896 110.744 419.104 108.316 417.716 105.839C416.329 103.361 414.149 101.28 411.176 99.5955C408.302 97.8117 404.685 96.9198 400.324 96.9198C395.468 96.9198 391.257 98.4063 387.689 101.379C384.221 104.352 381.842 108.267 380.554 113.123H420.095Z" fill="#5E5E5E"/>
<path d="M317.93 85.3252H333.389V96.3252H334.281C335.867 92.5595 338.741 89.4378 342.903 86.9603C347.065 84.3838 351.326 83.0955 355.687 83.0955C359.254 83.0955 362.178 83.591 364.457 84.582V101.677C361.087 99.9919 357.322 99.1496 353.16 99.1496C347.808 99.1496 343.299 101.231 339.632 105.393C336.065 109.456 334.281 114.46 334.281 120.406V159.055H317.93V85.3252Z" fill="#5E5E5E"/>
<path d="M294.594 72.8384C291.522 72.8384 288.896 71.7979 286.715 69.7168C284.634 67.5366 283.594 64.9105 283.594 61.8384C283.594 58.7663 284.634 56.1897 286.715 54.1087C288.896 51.9285 291.522 50.8384 294.594 50.8384C297.666 50.8384 300.242 51.9285 302.324 54.1087C304.504 56.1897 305.594 58.7663 305.594 61.8384C305.594 64.9105 304.504 67.5366 302.324 69.7168C300.242 71.7979 297.666 72.8384 294.594 72.8384ZM286.418 85.325H302.769V159.055H286.418V85.325Z" fill="#5E5E5E"/>
<path d="M211.938 52.6221H276.6V68.5275H228.586V99.1492H271.843V114.906H228.586V159.055H211.938V52.6221Z" fill="#5E5E5E"/>
<path d="M51.2275 191.109C59.4031 194.399 68.2727 196.352 77.5857 196.677C90.1896 197.117 102.175 194.511 112.89 189.561C100.041 184.513 88.4043 177.131 78.4729 167.952C72.0352 178.26 62.5135 186.401 51.2275 191.109Z" fill="#FF9100"/>
<path d="M78.4711 167.955C55.8006 146.988 42.0477 116.641 43.21 83.3558C43.2478 82.2749 43.3048 81.1947 43.3715 80.1148C39.3113 79.0647 35.0725 78.4239 30.7103 78.2716C24.4663 78.0535 18.4195 78.8279 12.7108 80.4355C6.659 91.0365 3.00696 103.2 2.552 116.228C1.37785 149.852 21.7254 179.231 51.2257 191.112C62.5117 186.404 72.0331 178.272 78.4711 167.955Z" fill="#FFC400"/>
<path d="M78.472 167.954C83.7428 159.519 86.9386 149.63 87.3106 138.976C88.2893 110.95 69.4486 86.8412 43.3725 80.1137C43.3058 81.1936 43.2487 82.2738 43.211 83.3547C42.0486 116.64 55.8015 146.987 78.472 167.954Z" fill="#FF9100"/>
<path d="M84.3945 1.33524C69.5432 13.233 57.8158 28.9212 50.7205 46.9936C46.6583 57.3453 44.1056 68.4647 43.3603 80.1206C69.4365 86.8481 88.2772 110.957 87.2985 138.983C86.9264 149.637 83.7213 159.516 78.4599 167.961C88.391 177.149 100.028 184.522 112.877 189.57C138.667 177.649 156.965 151.996 158.025 121.654C158.711 101.995 151.158 84.4744 140.485 69.6852C129.214 54.0442 84.3945 1.33524 84.3945 1.33524Z" fill="#DD2C00"/>
</svg></div>

Firebase allows developers to create a fully featured backend on top of servers and APIs operated by Google.

### overall benefits

- solid developer experience
- it scales to world-scale use
- generous free-tier and pay-as-you-go pricing
- high quality docs, well supported by AI models
- actively developed and maintained

### main backend components covered in this document

- authentication with Firebase Auth
- database with Cloud Firestore
- storage with Cloud Storage
- serverless functions with Cloud Functions

### focus of this document: web-centric

We create a backend for web-apps, and use the web-centric client SDKs. We default to TypeScript, and pick Node.js as the runtime for Cloud Functions.



# CLI tool

The Firebase CLI tool enables several workflows:

- Emulate the Firebase backend locally, to run it and debug it at no cost and without a deploy step.
- Scaffold the Cloud Functions' directory, and deploy Cloud Functions.
- Submit secrets and API keys to Google, making them available to Cloud Functions.
- Add and deploy security rules.
- List the Firebase projects linked to the Google account.

### the CLI executable

The _firebase-tools_ package installs the _firebase_ CLI executable.

```bash
npm install -g firebase-tools
firebase
```

[Release notes](https://github.com/firebase/firebase-tools/releases)

### underlying Google account

Firebase projects are linked to a Google account.

```bash
firebase login:list # prints current Google account
firebase login
firebase logout
```

### list projects and select one

```bash
firebase projects:list
firebase use imagetales
```

### project configuration and scaffolding

The _init_ command enables several workflows. We can:

- scaffold the Cloud Functions directory
- set up and configure emulators
- add security rules for Firestore and Cloud Storage

```bash
firebase init
```

### help

- print the list of Firebase commands.
- print the details about a given command.

```bash
firebase help

firebase help emulators:start
firebase help deploy
```

### list deployed functions, deploy functions

```bash
firebase functions:list

firebase deploy --only functions
firebase deploy --only functions:requestPlanet
```

### manage secrets

```bash
firebase functions:secrets:access ABC_API_KEY
firebase functions:secrets:set ABC_API_KEY
firebase functions:secrets:destroy ABC_API_KEY
```

### start and config emulators

```bash
firebase emulators:start
firebase emulators:start --import emulator-data --export-on-exit
```

We set which emulators to run with `firebase.json`. We scaffold this file with _firebase init_. If the port is omitted, the emulator uses the default one.

```json
{
    "emulators": {
        "firestore": { "port": 8080 },
        "auth": { "port": 9099 },
        "functions": { "port": 5001 },
        "storage": { "port": 9199 },
        "ui": { "enabled": true }
    }
}
```

### manage and deploy security rules

The storage emulator requires storage access rules.

- We define Storage rules in _storage.rules_.
- We define Firestore rules in _firestore.rules_
- We refer to the rules in `firebase.json`:

```json
{
    "storage": { "rules": "storage.rules" },
    "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json"
    }
}
```

We deploy the rules:

```bash
firebase deploy --only storage
firebase deploy --only firestore:rules
```

### _gcloud_: Google Cloud CLI tool

_gcloud_ enables some operations not available with the _firebase_ tool, such as listing secrets of a given project or describing a Storage bucket.

We call _gcloud_ from the Google Cloud Console's [_Cloud Shell_](https://console.cloud.google.com/welcome?cloudshell=true) (it is pre-installed), or we install it locally from [an archive provided by Google](https://docs.cloud.google.com/sdk/docs/install-sdk).

```
gcloud secrets list --project <PROJECT_ID>
gcloud storage buckets describe gs://abcd.firebasestorage.app
```



# SDKs

We interact with the backend with the help of SDKs. In this book, we describe the JavaScript SDKs.

### client SDKs

The client SDKs run on unprivileged clients, such as browsers. They can also run in Node.js apps that want to run unprivileged.

The client SDKs live in the _firebase_ package:

    npm i firebase

- [JavaScript client SDK - Release notes](https://firebase.google.com/support/release-notes/js)

### admin SDK: privileged environments

The admin SDK is designed to run on secure environments as it relies on privileged service accounts.

The admin SDK authenticates itself against Google servers using a privileged account called a _service account_. _Service accounts_ are managed by Google, scoped to a Firebase project and have specific entitlements. Such accounts are not subject to security rules and are already authenticated.

As Cloud Functions run on Google servers pre-configured with appropriate _service accounts_, it is fitting and convenient to use the admin-SDK. The _firebase-admin_ package is designed to run on a _Node.js_ server:

    npm i firebase-admin

- [Node.js admin SDK - Release notes](https://firebase.google.com/support/release-notes/admin/node/) ([GitHub version](https://github.com/firebase/firebase-admin-node/releases))
- [Node.js admin SDK - Reference](https://firebase.google.com/docs/reference/admin/node/firebase-admin)

### Cloud Functions SDK

We define Cloud Functions with the (Node.js) Cloud Functions SDK.

- [Node.js Cloud Functions SDK - Release notes](https://github.com/firebase/firebase-functions/releases)

We have the package listed as a dependency after scaffolding the Cloud Functions directory with _firebase init_.

```json
"firebase-functions": "^7.0.0",
```



# Project setup and initialization

### identify the Firebase project (client SDK)

The config object stores credentials to identify the Firebase project when interacting with Google servers:

```ts
const firebaseConfig = {
    apiKey: "....",
    authDomain: ".....firebaseapp.com",
    projectId: "....",
    storageBucket: ".....firebasestorage.app",
    messagingSenderId: "....",
    appId: "....",
}
```

### register one or more configs

We register the config (client SDK) and keep a reference to the app helper , which we initialize other services with:

```ts
const app = initializeApp(firebaseConfig)
```

When working with several Firebase projects, we get a helper for each. The first helper has a _"[DEFAULT]"_ internal string identifier. We provide string identifiers for the additional project we want to work with.

```ts
const app1 = initializeApp(firebaseConfig1)
const app2 = initializeApp(firebaseConfig2, "bar")
```

When initializing the admin SDK on Google servers that run Cloud Functions, the admin SDK finds the credentials on its own. We initialize it without a config:

```ts
const app = initializeApp()
```



# Auth Overview



### authenticate app users

The Auth client SDK authenticates users, and notifies the app about Auth events. It provides several authentication flows.

### the _auth_ helper and reading _currentUser_

We keep a reference to the _auth_ helper to read `currentUser`. We also use it in auth related functions.

```ts
const auth = getAuth(app)
auth.currentUser // User | null
```

_currentUser_ starts as _null_. When the SDK has finished loading, and given that the user has logged in, _currentUser_ switches to a _User_ instance.

As a _User_ instance, It exposes the user identifier (_uid_). The other properties are optional:

```ts
currentUser.uid
currentUser.email
currentUser.phoneNumber
currentUser.displayName
currentUser.isAnonymous
```

### react to authentication events

We register a callback on _onAuthStateChanged_, which Firebase runs on auth events. Firebase gives us a _user_ object (of type _User_ | _null_).

```ts
onAuthStateChanged(auth, (user) => {
    if (user) {
        // user.uid
    }
})
```

Auth events:

- the auth SDK has finished loading and no user is authenticated
- the user has registered (sign up)

- the user has logged in (sign in)
- the user has logged out (sign out)

Login occurs in three specific scenarios:

- the user fills out the standard login form or logs in through an identity provider (hard-login)
- the user is recognized by the SDK and is logged in automatically (credentials stored in browser)
- (canonically a registration) the user is automatically logged in after a successful sign-up. Note: a single authentication event occurs.

### _React_ patterns

We make the authentication status part of the _React_ state. For example, we work with a _isSignedIn_ variable. We make the display of the authenticated area conditional on _isSignedIn_ being true.

On page load, the Auth SDK is loading: It's best to wait for the SDK to load before making any use of _isSignedIn_, given that the state should be indeterminate.

As such, we track the loading state in a one-off state variable, which becomes _true_ on the first authentication event. Only then do we set _isSignedIn_ with correct state and make use of it.

If we were to read _isSignedIn_ before load, and because we initialize it to _false_ for simplicity, we would have a rapid UI flicker when it switches from false to true if applicable.

```tsx
const [hasLoaded, setHasLoaded] = useState(false)
const [isSignedIn, setisSignedIn] = useState(false) // the initial state shouldn't be relied upon.

useEffect(() => {
    const unsub = onAuthStateChanged(auth, (user) => {
        setHasLoaded(true)
        setisSignedIn(Boolean(user)) // accurate state
    })
    return unsub
}, []) // subscribe once, unsubscribe on unmount.

if (!hasLoaded) return null
if (!isSignedIn) return <Lobby />
return <Ingame />
```

### sign out

sign out is consistent across all authentication flows:

```ts
signOut(auth)
```

# Email-Password accounts



A provider that relies on collecting the user's email and password.

### registration and hard-login

On success, we receive a _credential_ of type _[UserCredential](https://firebase.google.com/docs/reference/js/auth.usercredential)_.

register:

```ts
createUserWithEmailAndPassword(auth, email, password).then((credential) => {
    credential.user // User
})
```

hard login:

```ts
signInWithEmailAndPassword(auth, email, password).then((credential) => {
    credential.user // User
})
```

### send a password reset email

We ask Firebase to send a password-reset email to the provided email. We can customize the email content through the Firebase console:

```ts
sendPasswordResetEmail(auth, email)
```

### email account's _providerData_ (implementation detail)

The user object of type _[User](https://firebase.google.com/docs/reference/js/auth.user.md)_ has a _providerData_ field with _password_ as the _providerId_ value:

```json
{
    "providerData": [
        {
            "providerId": "password",
            "uid": "user@example.com",
            "email": "user@example.com",
            "displayName": null,
            "phoneNumber": null,
            "photoURL": null
        }
    ]
}
```

# Identity Providers



We allow users to authenticate with external provider accounts, such as with their Google account or Apple account.

### select one or several providers

Note: We enable providers in the Firebase console.

```ts
const gProvider = new GoogleAuthProvider() // Google account provider
```

### authentication flows

Alternative flows:

- the user authenticates through a popup window.
- the user authenticates through a redirect.

A flow is initiated through a user action, such as tapping a button. Both flows handle sign-in and sign-up through a single, undiscriminated action. As such, we use generic labels, such as:

- _Continue_ with Google
- _Authenticate_ with Google

On success, a flow triggers an authentication event. The flow functions return a credential object (_UserCredential_), that exposes the user object:

```ts
const credential = await signInWithPopup(auth, gProvider)
credential.user // User
```

Note: We can detect it is a new user through a helper method:

```ts
const userInfo = getAdditionalUserInfo(credential)
if (userInfo?.isNewUser) {
}
```

### popup flow specifics

The popup flow may fail if the browser doesn't allow popups.

```ts
const credential = await signInWithPopup(auth, gProvider)
```

### redirect flow

The redirect flow relies on navigating to another page and navigating back.

It requires extra work unless the website is hosted on Firebase Hosting.

# Anonymous accounts



Register an account with no personal information from the user:

```ts
signInAnonymously(auth)
```

The generated credentials are stored in the browser: users cannot access their account from other devices, and cannot recover it if they lose the credentials (browser wipe).

Auth-triggered Cloud Functions only partially support anonymous accounts:

- The v1 auth functions such as `onCreate()` correctly trigger.
- The v2 auth blocking functions such as _`beforeUserCreated()`_ don't trigger (as of writing)

### check if the account is anonymous

On the client, we check the `isAnonymous` prop from _currentUser_:

```ts
auth.currentUser?.isAnonymous
```

In auth-triggered Cloud Functions, we read _providerData_ (from the _UserRecord_ which resembles the client SDK's _User_).

```ts
export const onRegisterNonBlocking = auth.user().onCreate(async (userRecord) => {
    userRecord.providerData.length === 0 // empty array for anonymous accounts
})
```

### convert to a non-anonymous account (client SDK)

We link the account to another provider. Since the user already exists (_auth.currentUser_), we provide it to the linking function. We link to an email provider or to an identity provider:

```ts
// email
const emailCred = EmailAuthProvider.credential(email, password)
await linkWithCredential(auth.currentUser, emailCred)

// Google account with popup
const gProvider = new GoogleAuthProvider()
await linkWithPopup(auth.currentUser, gProvider)
```

# Manage users



We can manage users in the Firebase console or programmatically via the admin-SDK:

```ts
import { getAuth } from "firebase-admin/auth"
const auth = getAuth()
```

### list users

_listUsers()_ fetches at most 1000 users at once. If we have more users, we use pagination.

```ts
const result = await auth.listUsers() // implied 1000 max
const users = result.users

users.forEach((user) => {
    user // UserRecord

    user.uid
    user.email

    // HTTP-date string (RFC 1123)
    user.metadata.creationTime // "Tue, 13 Jun 2023 17:00:00 GMT"
    user.metadata.lastSignInTime // "Wed, 14 Jun 2023 17:00:00 GMT"
})
```

# Firestore



### conceptual

Firestore is a _schema-less_ database made of collections and documents of loose shape (NoSQL), most similar to MongoDB.

- A _collection_ is a set of documents.
- A _document_ is a set of fields holding primitive data types (number, string, timestamps...) or object types (maps and arrays). A document has up to 20k fields and stores up to 1 MiB of data.
- A _reference_ serves to refer to a collection or to a document. It doesn't guarantee the collection or document's existence in the database: It's merely a path that points to a location.

### import paths and documentation

We interact with the database with the client SDK or with the admin SDK. The admin SDK's firestore sub-package is a wrapper around a _google-cloud_ [package](https://docs.cloud.google.com/nodejs/docs/reference/firestore/latest): It has the same syntax and capabilities.

- [client SDK (JavaScript)](https://firebase.google.com/docs/reference/js/firestore_.md#@firebase/firestore)
- [admin SDK (Node.js)](https://firebase.google.com/docs/reference/admin/node/firebase-admin.firestore) (wrapper), [@google-cloud/firestore (Node.js)](https://docs.cloud.google.com/nodejs/docs/reference/firestore/latest/)

```ts
"firebase/firestore" // client SDK
"firebase/firestore/lite" // client SDK

"firebase-admin/firestore" // admin SDK
```

### helper object

We init a _db_ object, for use in Firestore-related functions.

```ts
// const app = initializeApp()
const db = getFirestore(app)
```

# Collection



## Collection Reference

### use the collection reference

We use a collection reference when an individual document reference is not needed or not yet available:

- fetch all documents (it acts as a query): `getDocs(colRef)`

- build a query (targeting the collection): `query(colRef, filters..)`

- build a random-ID document reference: `doc(colRef)`, or one that refers to a specific document: `doc(colRef, docId)`
- add a random-ID document to the collection in a single step: `addDoc(colRef, data)`.

### build a collection reference

We use the path that identifies the collection uniquely. Root collections have the simplest path: the collection name, such as `"users"` (no starting slash). Sub-collections' paths are built from several components.

We set the path as:

- a string, with slash separators.

- a sequence of strings, with no slash separators.

```ts
const colRef = collection(db, "users")
const colRef = collection(db, `users/${uid}/custom_list`)
const colRef = collection(db, "users", uid, "custom_list")
```

```ts
const colRef = db.collection(`users/${uid}/custom_list`) // admin SDK
```

### TypeScript: a collection's documents as _DocumentData_

Collections are schema-less: they don't define the shape of their documents.

When receiving data from the database, the client SDK instantiates documents with no regard to the content: documents are of any shape and may differ from one another. It types them as _DocumentData_, which doesn't provide information about the content.

### TypeScript: annotate the document's type at the collection level.

We provide a more precise type at the collection reference level. The simplest way to do it is through a type assertion:

```ts
const colRef = collection(db, "players") as CollectionReference<Player, Player>
```

## Converter (optional)

### the case for a converter

The SDK supports working with two document shapes on the client:

```ts
CollectionReference<AppModel, DbModel>
```

_DbModel_ represents the object that the SDK instantiates from the raw data. It is _DocumentData_ by default.

We can add a converter to transform it to a different shape for use in the app.

_AppModel_ represents the object after the converter's transformation. It also defaults to _DocumentData_. We set it to whatever type the converter converts to.

Before sending to Firestore, the converter transforms back _AppModel_ to _DbModel_.

Transformation examples:

- We transform the DbModel's _Timestamp_ field to an AppModel _Date_ field.
- We add properties to _AppModel_.

### implement the converter

We transform the documents at the app boundaries:

- upon receiving from Firestore (`fromFirestore()`)
- upon sending to Firestore (`toFirestore()`)

We define the functions and add them to the converter.

_fromFirestore()_ takes the snapshot as instantiated:

```ts
fromFirestore(snapshot: QueryDocumentSnapshot<FirestoreWorkout>): Workout{
		// to client shape
		// FirestoreWorkout -> Workout
		const firestoreItem = snapshot.data()
		const workout = { ...firestoreItem, date: firestoreItem.date.toDate()}
     return workout
    }
```

_toFirestore()_ takes the object in its _AppModel_ shape.

```ts
toFirestore(workout: Workout) {
		// to database shape
  	// Workout -> FirestoreWorkout
        	return { ...workout, date: Timestamp.fromDate(workout.date)}
    }
```

We gather the transforms in the converter (_FirestoreDataConverter_). While the type are inferred from the transforms, we can still add them at the converter level:

```ts
// FirestoreDataConverter<AppModel, DbModel>
const myConverter: FirestoreDataConverter<Workout, FirestoreWorkout> = {
    toFirestore() {},
    fromFirestore() {},
}
```

We attach it to the collection reference to let it type its documents.

```ts
const colRef = collection(db, "players").withConverter(conv)
```

# Document



## Document reference

The document reference identifies a document within the database, and embeds meta information:

```ts
docRef.id // "Nk....WQ"
docRef.path // "users/Nk....WQ"
docRef.parent // colRef
```

### use the document reference

We use the reference for most CRUD operations:

- read the document: `getDoc`

- update an existing document (it errors if the document doesn't exist): `updateDoc`

- delete the document: `deleteDoc`
- create the document, or override an existing one (upsert): `setDoc`

Note: `addDoc()` works without a document reference since it generates a new one on the fly.

### build a document reference

The document's path identifies it uniquely. We set the path as a single string or build it from string components:

```ts
const docRef = doc(db, "users", id)
const docRef = doc(db, "users/Nk....WQ")

// const docRef = collectionRef.doc("NkJz11WQ") // admin sdk
```

Alternatively, we provide the collectionRef and the document ID, or only the collectionRef. In the latter case, the SDK generates a random ID.

```ts
const docRef = doc(collectionRef, id)
const docRef = doc(collectionRef) // random ID
```

### read document at reference (get)

The get operation succeeds even when no document exists. We receive a _Document snapshot_ which may be empty.

As such, checking the document existence requires to read inside the _Document snapshot_.

```ts
getDoc(docRef) // DocumentSnapshot
// docRef.get() // DocumentSnapshot
```

## Document snapshot

The _Document snapshot_ is a wrapper that doesn't guarantee the document existence. It exposes the document (or its absence) via a getter. The document's type is _DocumentData_ or the more specific type we provided. It can also be _undefined_, unless it comes from a query (see _Query_)

Note: _data()_ is a function because it accepts some configuration.

```ts
docSnapshot.exists()
docSnapshot.data() // DocumentData | undefined
```

It also exposes helpers and metadata.

```ts
docSnapshot.id // NkJ...7f
docSnapshot.ref // DocumentReference
docSnapshot.metadata // SnapshotMetadata
```

Query a specific field

```ts
docSnapshot.get("address.zipCode") // low use
```

### real-time listener on a single document

Set up a real-time listener on a (single) document reference:

```ts
const unsub = onSnapshot(docRef, (docSnapshot) => {
    docSnapshot.data() // DocumentData | undefined
})
```

# Query



## overview

A query matches documents based on a set of criteria, and not based on a set of document references.

### the result of a query: a query snapshot

The snapshot hosts a list of document snapshots (_docs_). The list is empty when no match occurs.

Otherwise, it contains only non empty snapshots, of type _QueryDocumentSnapshot_, which is _DocumentSnapshot_ except that `data()` cannot be undefined.

```ts
querySnapshot.docs // list of document snapshots (QueryDocumentSnapshot)
querySnapshot.empty

docSnapshot.data() // DocumentData (not undefined)
```

```ts
const cats = querySnapshot.docs.map((docSnap) => docSnap.data())
```

### a collection reference is a query

A collection ref can serve as a query, the one that targets all documents (get):

```ts
getDocs(colRef)
// getDocs(q)

colRef.get()
// q.get()
```

## build a query

We always provide the collection reference. Then, we can:

- add value-based filters
- set the order
- limit the count

```ts
const q = query(colRef, where(..), where(..), orderBy(..), limit(..))
// const q = collection(..).where(..).orderBy(..).limit(..)
```

### where filter: look for documents with a given value

We filter documents based on a value we want to find in a property. We request an exact value or one within a range. Depending on the data, we expect a single match or several.

Note: documents that do not possess the property _at all_ are filtered out.

For example, we look for a document whose _id_ is _user.id_:

```ts
where("id", "==", user.id)
// where(propertyName, operator, value)
```

We set the requirement for the value: exact match, being different, being smaller or larger, exact match with at least one value, or different from all values.

```ts
==
!=

<
<=
>
>=

"in" // the property is equal to either A, B or C
"not-in" // the property is different from A, B and C.
```

We can also ask the value to be included or excluded from the array if the property is an array.

```ts
"array-contains" // the array contains the value
"array-contains-any" // the array contains A, B or C..
```

### order documents based on a field

We order documents based on (the value of) a field, in the ascending or descending order. If omitted, the order defaults to ascending.

```ts
orderBy(propertyName, orderDirection)
orderBy("postCount", "asc")
orderBy("postCount", "desc")
```

We can start from a given value, e.g. documents that have at least (or more than) 10 posts.

```ts
startAt(10)
startAfter(10)
```

### pagination: cap the read, then read the next page

Get at most n documents:

```ts
limit(20)
```

To get the next page, we provide a cutoff document (snapshot), stored from the current batch: we then receive the document snapshots that starts after it:

```ts
query(colRef, startAfter(docSnapshot), limit(20))
```

## run the query (get)

### one time fetch

```ts
const qs = getDocs(query)
const qs = query.get()
```

### real-time listener

Set up a real-time listener on the query: we receive a query snapshot:

```ts
const unsub = onSnapshot(query, (qs) => {
    const documents = qs.docs.map((docSnapshot) => docSnapshot.data())
    setMessages(documents)
})
```

# Create and update documents



### targeted, strict document creation

On the admin SDK, we can perform strict targeted document creations, aka create a document with a controlled ID and expect a failure if the document already exists:

```ts
docRef.create(data)
```

The client SDK doesn't offer an equivalent function. Instead, we can do a two-step transaction where we read for document existence then write the document conditionally.

### random-ID document creation (_add_)

The client SDK prefers random-ID creation that always succeed because the document won't already exist by design (_add_):

```ts
addDoc(collectionRef, data)
// db.collection("message").add(data)
```

### upsert (_set_)

An upsert works regardless if a document exists or not. It is destructive, as it override any existing document.

```ts
setDoc(docRef, data)
// docRef.set(data)
```

### update documents

We assume the document already exists: we use the _update_ pattern or the _set_ _with_ _merge_ pattern.

The _update_ function is a strict update: it correctly fails if the document doesn't exist.

Both _update_ and _set merge_ expect a _change_ object. We type the _change_ as a _Partial_ or as a _Pick_ of the document:

```tsx
const change: Partial<User> = { displayName: "Johnny Appleseed" }
updateDoc(docRef, change)
// docRef.update(change)
```

_update_ uses the provided fields to replace the existing ones, the other fields being left unchanged.

To mutate a single field in an object field, we target it with _dot notation_. If we target the object instead, the omitted sub-fields are deleted (different from _set with merge_)

```ts
// sub-field
const change: Partial<User> = { "address.city": "Lyon" }
updateDoc(docRef, change)
```

If TypeScript complains about the dot notation, we use the _FieldPath_ overload:

```ts
updateDoc(docRef, new FieldPath("address", "city"), "Lyon")
```

### partial update with _set_ _and merge_

the merge option changes the meaning of _set_: we are now providing a change object, not the new object.

What we target in the change object is what gets changed, including sub-fields. The omitted sub-fields are preserved (deep merge): there is no need for dot notation:

```ts
const change = { address: { city: "Lyon" } } // only changes city in address

setDoc(docRef, change, { merge: true })
// docRef.set(data, { merge: true })
```

### relative change (increment, decrement)

We ask the server to change the field by _n_, which can be positive or negative. The current value is unknown:

```ts
const change = {
    activityScore: increment(1), // or e.g. -1
}

// docRef.update({
//    count: FieldValue.increment(1),
// })
```

### delete field

We ask the server to delete a field. This shortcuts the need to fetch the document first and store it second omitting the given field:

```ts
updateDoc(docRef, {
    fleet: deleteField(),
})

// docRef.update({
//    fleet: FieldValue.delete(),
// })
```

### server timestamp field

Ask the server to generate a Firestore timestamp value.

```ts
updateDoc(docRef, {
    count: serverTimestamp(),
})

// docRef.update({
//    count: FieldValue.serverTimestamp(),
// })
```

### delete document

```ts
deleteDoc(docRef)
// docRef.delete()
```

# Batch writes



We gather writes in a batch object and ask Firebase to perform (_commit_) all the writes at once.

The operation is atomic: if one write fails, the others fail as well. This prevents a broken state where only some documents are updated.

A single network request is sent.

Note: the functions are namespaced on `batch` both for the client SDK and the admin SDK.

### batch changes then commit

Collect up to 500 writes in a batch object, and execute them with `commit()`.

In this example, we use `update()`, but we could also use `set()` or other methods.

```ts
const batch = writeBatch(db)
// const batch = db.batch() // admin SDK

const change = { timezone: "Europe/London" }

batch.update(docRef1, change)
batch.update(docRef2, change)
// ..
// ..

await batch.commit()
```

### other batch operations

```ts
batch.set(docRef, data)
batch.set(docRef, change, { merge: true })
batch.update(docRef, change)
batch.delete(docRef)
batch.create(docRef, data) // Admin SDK
```

# Transactions



Read and write atomically with transactions

### conceptual

Transactions are for operations where a preliminary read is required to determine the applicability, nature and extent of a tentative write.

A naive read and write is subject to desync: by the time the write order hits the database, the motivating condition may have changed: the data can change between the database read and the database write, as simple reads have no lock effect.

A transaction is a guarantee that by the time the database commits the write, the data hasn't changed since the initial read, so that the check that was performed on the data is still relevant.

For example, if _credits_ is positive and sufficient, the condition is fulfilled, but by the time we are about to commit the purchase, we want _credits_ not to have changed since the read.

### implementation

The simplest way to guarantee it is to lock the document between the read and the write. The Admin SDK locks the document during the read to write time-window.

The client SDK doesn't lock the document, because the time between the read and write orders can become overly long and degrade the UX for the rest of users. Instead:

- the SDK is aware of the document's version (by the time it was read), and asks the database to only perform the write if the document is still of this version (possibly tracked with an _updateTime_ flag or equivalent).
- The database allows changes initiated by other operations, if any.
- On receiving the conditional write order, the database enforces the condition: it proceeds only if the document hasn't changed. Otherwise, it rejects the transaction: it is up to the client SDK to attempt a new transaction. The client SDK does retry by default, up to 5 total attempts. (_retry_ strategy).

This pattern is called _emulated optimistic concurrency_.

See also: [Transaction serializability and isolation (Firestore)](https://firebase.google.com/docs/firestore/transaction-data-contention?utm_source=chatgpt.com).

### the _runTransaction_ function

_runTransaction_ expects a callback. _transaction_ is a helper that holds the read and write methods (_get_, _update_, _set_).

Note that we _await_ reads, but don't _await_ writes, since writes are grouped up on the transaction object and sent all at once.

In case of failed preconditions, we abort the transaction with a throw:

```ts
await runTransaction(db, async (transaction) => {
    // read
    const snapshot = await transaction.get(docRef)

    // check condition
    if (!snapshot.data()) throw Error("No such event!")
    const count = snapshot.data().count
    if (count >= 10) throw Error("Sorry, event is full!") // Abort

    // proceed
    transaction.update(docRef, { count: count + 1 })
})

// admin SDK
// await db.runTransaction(async (transaction) => {
// identical API
// })
```

# Timestamp value type (advanced)



Note: storing dates as ISO _strings_ is simpler and more portable.

As the Firestore database comes with a [native value type for storing dates](https://firebase.google.com/docs/firestore/data-model) called _timestamp_, we describe using this pattern in this article. The Firestore SDK comes with a _Timestamp_ type that represents a _timestamp_ field.

### storing timestamps

As we attempt to store data, the SDK detects Date and Timestamp fields and assumes we want to store them as _timestamps_.

```ts
const user = {
    createdAt: new Date(),
    createdAt_: Timestamp.now(),
}
```

When preparing data for the HTTP request, the SDK serializes Date objects and Timestamp objects to plain objects with a single _timestampValue_ property:

```json
{
  "createdAt": { "timestampValue": "2025-10-07T18:47:13.279000000Z" },
  "createdAt_": { "timestampValue": "2025-10-07T18:47:13.279000000Z" }
},
```

The database detects this pattern and sets the fields as _timestamps_.

### receiving timestamps

The SDK's _Timestamp_ type represents database _timestamps_. As we receive _timestamp_ fields from the database, the Firestore SDK instantiates them as _[Timestamp](https://firebase.google.com/docs/reference/node/firebase.firestore.Timestamp)_ objects.

# Firestore Security rules



We define the security rules in the Firebase console or in a _firestore.rules_ file, referenced by _firebase.json_. Firebase doesn't bill reads and writes denied by security rules.

rules version

```ts
rules_version = "2"
```

### firestore scope

We start by scoping the rules to _cloud.firestore_

```ts
service cloud.firestore {
    // ...
    }
```

### database scope

We scope the rules to the current database. The security rules only affect the current database, so this can be seen as superfluous. But we use the wildcard when querying separate documents (see below).

```ts
match /databases/{database}/documents {
    // ...
}
```

### set rules for a given collection

We target a collection. The document ID wildcard holds the requested document's ID. We can name it with what the document represents:

```ts
match /users/{user_id} { // document ID wildcard
    	// ...
}
```

### operations and condition

```
allow operation, operation: if condition;
```

operations

```
read
create
update
delete
```

### authentication, user ID

If the user is not authenticated, _request.auth_ is _null_. We can filter out unauthenticated users:

```
allow read: if request.auth != null;
```

The user's authentication _uid_ (if logged in) is available as _request.auth.uid_:

```ts
request.auth.uid
```

Note: if auth is null, trying to read uid triggers a failsafe mechanism that denies the request.

### authorize specific documents

Document ID based authorization: We authorize the operation if the document's ID matches some condition:

```ts
    match /players/{player_id} {
         allow read: if request.auth.uid == player_id;
    }
```

Field value based authorization: we authorize the operation based on the value of a specific field. Either from the requested document or from the uploaded document.

- _resource.data_ represents the requested document.
- _request.resource.data_ represents the uploaded document
- For example, we check the requested document's _owner_ property against _auth.uid_. In this case, we ignore the uploaded document's data which can be tampered with.

```ts
    match /planets/{planet_id} {
         allow read: if request.auth.uid == resource.data.owner.id;
    }
```

If the document is missing the field, the request is denied.

### authorization based on separate documents

We read a document with _get()_. It is a billed read.

### first example (do not use)

This unlocks a pattern where we read authorization data in a separate document, such as in the user document, which would store the user's entitlements:

```ts
get(/databases/$(database) / documents / users / $(request.auth.uid)).data.rank
```

For example, we read the user's rank in the database to authorize a write on any character:

```ts
    match /characters/{character_id} {
         allow update: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.rank == "Game Master";
    }
```

Note: We should use Firebase Auth custom claims instead:

```
request.auth.token.rank == "Game Master";
```

### second example

For example, we read the player's character's zone to determine if it can read the requested overworld character:

```ts
match /overworld_characters/{overworld_character} {
     allow read: if get(/databases/$(database)/documents/characters/$(request.auth.uid)).data.zone == resource.data.zone;
}
```

Note:

- if a query matches 10 documents, the get() is run only once, so it only triggers a single read
- if a query, by its nature, could match at least one document that is not authorized by the security rule, the entire query is rejected. This forces the client to query only authorized documents. In the example, it forces the client to use a where() clause instead of fetching all overworld_characters. That is, we cannot rely on security rules to filter documents out of a broad query.

### payload validation

`request.resource.data` is the request's payload. We can validate critical fields:

```ts
	// simple check
request.resource.data.age >= 0

  // check against auth uid.
request.auth.uid == request.resource.data.uid;

  // check both requested document and uploaded document
  allow update,delete: if
  request.auth.uid == resource.data.uid
  &&
  request.auth.uid == request.resource.data.uid;
```

Alternative: We can perform validation in Cloud Functions and forbid writes coming from the client.

# Storage



### reference

- [client SDK - Storage](https://firebase.google.com/docs/reference/js/storage)

### file terminology

Firebase Storage is a wrapper around Google's [Cloud Storage](https://cloud.google.com/storage/?hl=en), a _cloud storage_ service. It is technically an _object storage_ service because it stores immutable _objects_ in a flat _bucket_, instead of files in a hierarchical filesystem.

Firebase Storage reintroduces the concept of files, folders and file hierarchy, and uses that terminology exclusively. Among other things, It does so by naming objects with their hierarchical path such as `public/abc.png`.

### project's default bucket (implementation detail)

A Firebase project is given a default bucket, with a given URI:

```ts
"gs://<PROJECT-ID>.firebasestorage.app"
"gs://<PROJECT-ID>.appspot.com" // old default bucket URIs
```

The bucket's URI serves to distinguish it from other buckets.

- It is made of two components: a `gs://` prefix and a domain name.
- The default bucket's domain uses the project's name as a subdomain, which makes it globally unique.
- If we add another bucket, we pick a globally unique name by ourselves:

```
"gs://<GLOBALLY-UNIQUE-ID>" // non-default bucket URI
```

The URIs only act as identifiers. There is no matching HTTP endpoint and no server listening to, for example, `abc.firebasestorage.app`.

### storage helper

We get a storage helper for use in various storage related functions:

- We don't name it _storage_ because Firebase already exports a _storage_ variable. We use another name such as _storageService_ or _bucket_.
- The client SDK uses the default bucket unless we specify another one in the initializer:

```ts
const storageService = getStorage(app)
const storageService = getStorage(app, "gs://...")

// const bucket = getStorage().bucket(); // admin SDK
```

# File references and metadata



### file path

A file path uniquely identifies a file in the bucket. It includes the file extension. It starts from the bucket's root.

### file reference

- We use references to interact with files
- A file reference does not guarantee the file existence.
- We build them with file (full) paths:

```ts
const fileRef = ref(storage, "tts/2F14Izjv.mp3")
// const fileRef = bucket.file("tts/2F14Izjv.mp3") // admin SDK
```

Note: `ref` can also build folder references.

The properties are of limited use:

```ts
ref.bucket // "abc.firebasestorage.app"
ref.fullPath // "tts/abc.mp3"
ref.name // "abc.mp3"

// computed references
ref.parent // ref(storage, "tts")
ref.root // ref(storage, "/")
```

### file metadata

A file metadata, of type _[FullMetadata](https://firebase.google.com/docs/reference/js/storage.fullmetadata)_, or _FileMetadata_ on the admin SDK, contains various information about the file:

```ts
metadata.size // 1048576 (bytes)
metadata.contentType // "audio/mpeg" (MIME type)
metadata.timeCreated // "2026-01-04T12:34:56.789Z"

metadata.ref // file reference

// repeat from fileRef
// metadata.bucket
// metadata.fullPath
// metadata.name
```

We fetch an existing file's metadata:

```ts
const metadata = await getMetadata(fileRef)

// admin SDK
// const [metadata] = await fileRef.getMetadata()
```

# List files and folders



### folders and prefix terminology

The API describes folders as _prefixes_, but the docs also mention _folders_.

### folder existence

A file, by its name alone, can create one or more nested _folders_. It occurs when its name contains subpaths. For example, _abc/def/hello.pdf_ creates two folders: _abc_ and _def_. Those folders are an artificial byproduct.

By design, those folders can't be empty, because they derive from a nested file.

### use a folder reference to list its content

We build a folder reference to list its content. It outputs a shallow list: we see the top level files and folders.

The list discriminates files (_items_) from folders (_prefixes_), putting them into separate arrays, but both arrays are typed with the same _StorageReference_ element type.

Note: _list()_ is a capped version that expects a count limit.

```ts
folderRef = ref(storage, "uploads")

const result = await listAll(folderRef)
const result = await list(folderRef, { maxResults: 100 })

result.items // StorageReference[]
result.prefixes // StorageReference[]
```

# Read, download files



### general considerations

- The client SDK's functions are subject to access-control rules.
    - Some functions allow the user, after access-control, to save a bearer URL which is not subject to security rules. This pattern is a one-off access control.

- Download workflows are influenced by the browser restrictions regarding the file's URL.

### get a HTTP URL on the client

We request a read URL. Access control is performed during such request.

The returned URL is a bearer URL, which is not subject to access-control. We consume it as a regular URL, outside the realm and control of the Storage SDK.

Note: the URL remains valid unless manually revoked at the file level in the Firebase Console, or with the admin SDK.

```ts
getDownloadURL(fileRef).then(url => ...)
```

### consume a cross-origin HTTP URL on the client (browser-specific)

The bucket's file lives on a separate origin than the origin that ships the web-app. For the browser, the file's URL is _cross-origin_. The challenges and patterns to consume a _cross-origin_ URL are not specific to Firebase.

The way we consume the URL determines if CORS headers are necessary:

- The browser allows _cross-origin_ URLs in media elements' _src_ attribute (hot linking), with no CORS header requirement.
- The browser allows navigating to _cross-origin_ URLs (basic browser behavior). For example, we navigate to an image in a new tab.
- The browser _doesn't allow_ background fetch of cross-origin resources unless explicit CORS headers are present on the server. This applies to _fetch()_ and functions that rely on it.

Buckets do not have permissive CORS headers by default, but we can add them on demand. CORS headers whitelist one, several or all domains. We use _gcloud_ to whitelist our domain (see the dedicated CORS chapter).

### download a Blob with the client SDK

A blob is an opaque object that we fetch and transform to a local URL for easier saving. When using _getBlob()_:

- access rules are enforced
- CORS headers are required (it uses _fetch()_ under the hood)

We create a _local_ (_same-origin_) URL out of the blob, to avoid the browser restrictions against _cross-origin_ URLs. It restores the ability to download content through a single click, without navigating to a different URL (see below).

```ts
getBlob(fileRef).then((blob) => {
    // create a local URL and trigger download imperatively
})
```

### add the download attribute to an anchor tag with a local URL

The _download_ attribute on anchor tags (`<a href="" download>`) offers one-click downloads for _same-origin_ URLs or _local_ URLs.

For _cross-origin_ URLs, clicking the anchor tag triggers standard browser navigation instead: the browser navigates to the resource and shows its full URL.

### create a local URL out of a blob (browser specific)

This example also triggers download programmatically, and revokes the local URL for clean up. We set the user-facing file name by setting the _download_ attribute:

```ts
// 3. Create a local URL out of the blob
const objectURL = URL.createObjectURL(blob)

// 4. Use the local URL and trigger the download
const link = document.createElement("a")
link.href = objectURL
link.download = img.id + ".png"
document.body.appendChild(link)
link.click()
document.body.removeChild(link)

// 5. Clean up by revoking the local URL
URL.revokeObjectURL(objectURL)
```

# Upload data



## client SDK

### upload a _Blob_ or a _File_

We prepare some data in a JavaScript _Blob_ or _File_ object, and upload it to the reference:

```ts
const result = await uploadBytes(fileRef, file) // File object
```

- The upload is a non-conditional upsert which overrides existing files.
- It makes the file immediately _downloadable_ through the SDK read functions.
- On success, we receive an _UploadResult_, which wraps the bucket file's metadata and the file reference.

```ts
result.metadata // FullMetadata
result.ref
```

### (advanced) upload and track the progress

For each tick, we receive a snapshot. We may show the upload progress.

```ts
const uploadTask = uploadBytesResumable(ref, file)

uploadTask.on(
    "state_changed",
    /* on snapshot */
    function (snapshot) {
        // snapshot.bytesTransferred
        // snapshot.totalBytes
        // snapshot.state // "paused" | "running"
    },
    function (error) {},
    function () {
        /* on completion */
        getDownloadURL(uploadTask.snapshot.ref).then(/**/)
    },
)
```

## admin SDK

### upload a Node.js _Buffer_

We prepare some data in a Node.js _Buffer_, and upload it to the reference.

```ts
await fileRef.save(imageBuffer, {
    resumable: false,
    metadata: {
        contentType: `image/png`,
        cacheControl: "public, max-age=31536000, immutable",
    },
})
```

Note: it doesn't make the file _downloadable_ for clients: a client _getDownloadURL()_ fails. This is because the underlying Firebase-specific download token in the GC storage object's metadata is missing.

### make it downloadable

To make it _downloadable_ for clients, we then use the admin SDK's `getDownloadURL()`. It adds a permanent download token to the underlying GC storage. It also returns the bearer URL (_tokenized_ URL that embeds this very access token, and is not subject to security rules).

We can store it in a database, return it to the client, or discard it and let the client SDK generates the URL on its own with `getDownloadURL()` (since it is now _downloadable_).

```ts
const url = await getDownloadURL(fileRef)
```

We can invalidate the access token from the Firebase console. It makes the file _non-downloadable_. The bearer URL becomes invalid.

### advanced: read and write the token

The token, if present, is in the _File_'s _metadata_ field. We should avoid setting this field manually when using _save_(). We use _getDownloadURL_ instead (see full example below).

```json
metadata: {
  firebaseStorageDownloadTokens: token
}
```

We can revoke the token:

```ts
await file.setMetadata({
    metadata: {
        firebaseStorageDownloadTokens: null,
    },
})
```

Or rotate the token

```ts
await file.setMetadata({
    metadata: {
        firebaseStorageDownloadTokens: randomUUID(),
    },
})
```

### upload image example (admin SDK)

We upload an image and make it readable by clients. We may store the bypass URL.

```ts
// 1.0 create a file reference
const fileRef = bucket.file(`generated/${userID}/cat.png`)

// 1.1 create a Buffer object
const imageBuffer = base64ToBuffer(base64Data)

// 1.2 upload the Buffer object
await fileRef.save(imageBuffer, {
    resumable: false,
    metadata: {
        contentType: `image/png`,
        cacheControl: "public, max-age=31536000, immutable",
    },
})
//  1.3 make it readable by client SDKs (generate a token).
const url = await getDownloadURL(fileRef)

//  1.4 store the bypass URL (if applicable)
//  ...
```

# Setting the bucket CORS header



Some read operations require the web client's domain to be whitelisted, through a bucket-side CORS header.

### read operations that require a CORS whitelist

Browser reads relying on background fetch rather than navigating to the URL require a CORS whitelist:

- _getBlob(fileRef)_ to get a _Blob_, which uses _fetch()_ under the hood.
- _getBytes(fileRef)_ to get an _ArrayBuffer_, which uses _fetch()_ under the hood.
- using _fetch()_ manually with a bearer (tokenized) URL.

### white-listing the domain

We add authorized domains to _cors.json_ and send it to Google through the CLI:

_cors.json_

```json
[
    {
        "origin": ["https://imagetales.io", "http://localhost:5173"],
        "method": ["GET"],
        "maxAgeSeconds": 3600
    }
]
```

Register _cors.json_:

```bash
gcloud storage buckets update gs://abc.firebasestorage.app --cors-file=cors.json
```

For debugging, we can get a description of the existing bucket CORS config:

```bash
gcloud storage buckets describe gs://abc.firebasestorage.app --format="default(cors_config)"
```

# Cloud Functions



Cloud Functions are serverless functions: we run code on servers operated by Google.

As it is a secure environment, we can run sensitive tasks: authenticate requests, perform server-side validation, use API keys, make sensitive database writes, and more.

Functions trigger on direct requests, or on events happening in the Firebase ecosystem, such as the registration of new users through Firebase Auth. They can also be triggered by a Cron job.

### trigger on direct requests: two options

The first option is to configure and establish a bare-bones REST-API endpoint, called a `HTTP` function. We configure the endpoint with an Express.js like API.

```ts
import { onRequest } from "firebase-functions/https"
```

The second option is to define a `Callable` function, a pattern that involves both a server SDK and a client SDK, which together do some heavy lifting on behalf of the developer, such as managing authentication, defining the type of the request's data and response, and offering streaming responses.

```ts
import { onCall } from "firebase-functions/https"
```

### select and deploy functions

The _main_ file determines which functions are deployed by default: all the ones that it exports. We determine the _main_ file in _package.json_. Since it must be a JavaScript file, we refer to the TypeScript compiler output file:

```json
{
    "main": "lib/index.js"
}
```

It is usually a barrel file that re-exports functions from their own files:

```ts
export { requestPlayer } from "./requestPlayer.js"
```

We deploy functions imperatively, all of them or some of them:

```bash
firebase deploy --only functions
firebase deploy --only functions:FOO
firebase deploy --only functions:FOO,functions:BAR
```

We can delete a function imperatively:

```bash
firebase functions:delete FOO
```

### configure TypeScript

We use a workflow that transpiles to JS since the functions are deployed as JavaScript functions.

The convention is to store TypeScript code in `src/` and transpile towards `lib/`. The main file is `lib/index.js`.

_tsconfig.json_ configures the transpilation, targeting the _Node.js_ runtime:

```json
{
    "compilerOptions": {
        "module": "NodeNext",
        "esModuleInterop": true,
        "moduleResolution": "nodenext",
        "noImplicitReturns": true,
        "outDir": "./lib",
        "rootDir": "./src",
        "sourceMap": true,
        "target": "es2022",
        "skipLibCheck": true,

        /* Linting */
        "strict": true,
        "noUnusedLocals": true,
        "noUnusedParameters": true,
        "noFallthroughCasesInSwitch": true,
        "verbatimModuleSyntax": true
    },
    "compileOnSave": true,
    "include": ["src"]
}
```

### use of the admin SDK

The use of the admin SDK is a natural fit from Cloud functions.

# Define Callable functions



The code we run in Callable functions has access to the user's authentication status along with the request's data.

Callable functions support streaming responses: we describe the pattern in a dedicated section.

## Overview and syntax

### synopsis

```ts
onCall<ReqData, Promise<ResData>>(options, callback)
onCall<ReqData, Promise<ResData>>(callback)
```

### the callback

The callback has access to the _request_ object ([CallableRequest](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.callablerequest)), which exposes _auth_ and _data_.

We define the callback async so it returns a promise. The connection is kept open until the promise settles.

```ts
;async (req) => {}
;async ({ auth, data }) => {}
```

- _auth_ is _undefined_ when the request is unauthenticated. It has _uid_ otherwise.
- _ReqData_ defines the data sent by clients.
- _ResData_ defines what the callback returns.

```ts
onCall<ReqData, Promise<ResData>>(async (req) => {
    req.auth // AuthData | undefined
    req.auth?.uid
    req.data // ReqData
    return { message: "" } // ResData
})
```

### add options

The _options_ object, of type _CallableOptions_, a subclass of [GlobalOptions](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.globaloptions.md#globaloptions_interface), sets the region, the secrets, and the number of instances and the concurrency for each instance:

```ts
const options: CallableOptions = {
    concurrency: 1,
    minInstances: 1,
    maxInstances: 1,
    region: "europe-west1",
}
```

An instance can handle several requests at once. By default, Firebase runs with no minimum and no maximum.

- Since there are no minimum (minInstances defaults to 0), Firebase doesn't run any instance when the endpoint is inactive. When a request is received, it spins up an instance, which requires some time (_cold start_), and keeps it alive for a while.
- To avoid cold starts, we can set minInstance to 1, which keeps the instance warm at all time but costs much more.
- We can limit _maxInstances_ to 1 if we prefer throttling traffic instead of scaling up.

_concurrency_ sets how many requests a single instance processes in parallel. Since it can process multiple requests in parallel by default, We only set it to 1 if we want a clean instance for each request or, if we also limit maxInstances to 1, if we want to process one request at a time.

## Streaming version

Streaming the response means to send small chunks of data with _sendChunk()_.

The third type argument (_StreamData_) defines what kind of chunk we stream. We usually stream _string_ chunks.

The _request_ exposes `acceptsStreaming`, which we read to check if the client supports streaming. When it does, the callback has access to an extra _response_ argument, on which we call _sendChunk()_.

```ts
onCall<T, U, V>(options, callback) // streaming Callable
```

```ts
onCall<ReqData, Promise<ResData>, StreamData>(async (request, response) => {
    if (response.acceptsStreaming) {
        response?.sendChunk("abc") // StreamData
        response?.sendChunk("def")
    } else return { message: ".." } // fallback
})
```

## Patterns

### halt and send an error immediately

We throw an _HttpsError_ with a specific error code which conforms to a [predefined list](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.md#httpsfunctionserrorcode). It defaults to _internal error_ if omitted.

```ts
throw new HttpsError("unauthenticated", "unauthenticated")
```

### logger

```ts
logger.debug("")
logger.info("")
logger.warn("")
logger.error("")
```

## Callable v1 (deprecated)

### define the function

```ts
functions.https.onCall(async (data, context) => {
    const auth = context.auth
    const message = data.message
    return { message: ".." }
})
```

### the context object

The context object provides the authentication details, if any, such as
the email, and the request metadata such as the IP address, or the raw
HTTP request. It is of type [CallableContext](https://firebase.google.com/docs/reference/functions/firebase-functions.https.callablecontext)

### check authentication

```ts
if (!context.auth) {
    throw functions.https.HttpsError("unauthenticated", "you must be authenticated")
}
```

# Invoke Callable functions



On the client, we invoke callable functions through specific handlers provided by the SDK.

### configure a functions helper with the firebase project and the region

- Since a client can interact with separate Firebase projects, we specify the project we target. We do so by providing the _app_ helper, which already identifies the project.
- Since Cloud function instances are region-specific, we specify which instance region we target. If omitted, the client SDK targets `us-central1`, which errors if no instance runs there:

```ts
const functions = getFunctions(app, "europe-west1")
```

### get a handle over the Callable function

We provide the function's name and the type arguments:

```ts
const requestPokemonCF = httpsCallable<ReqData, ResData>(functions, "requestPokemon")
```

### invoke and handle the result

- The request data, if any, is of type `ReqData` in our example.
- The returned value is of type `HttpsCallableResult<ResData>`, which is a container over the actual data, found in the _data_ property, of type _ResData_ in our example:

```ts
const result = await requestPokemonCF({ number: 151 })
result.data // ResData
```

# HTTP functions



### overview

Configure and establish a bare-bones REST-API endpoint, called an `HTTP` function. We use an Express.js like API. We respond with JSON, HTML, or plain text:

```ts
export const sayHello = onRequest((req, res) => {
    res.send("Hello from Firebase!")
})
```

### add options

```ts
const options: HttpsOptions = {
    region: "europe-west1",
    cors: true,
}
export const sayHello = onRequest(options, (req, res) => {})
```

### ExpressJS concepts and syntax

_req_ and _res_ objects have the shape of expressJS _req_ and _res_ objects. We can add middleware.

### call the endpoint: standard HTTP request (not Firebase specific)

We read the function's URL at deploy time.

We consume endpoints like regular REST API endpoints. The deployed endpoint URLs look like this:

```URL
https://requestPlanet-x82jak2-ew.a.run.app
```

# Run functions on Auth events



Register functions that react to Auth events. Blocking functions can deny the registration of a user. Non blocking functions run after the authentication event has occurred.

## Blocking functions

### run a function before the user is added to Firebase Auth

We perform validation, and, if applicable, deny the registration by throwing an error. Firebase Auth aborts user creation on throw. The Auth client SDK receives such error and can display it to the user.

```ts
export const onRegisterBlocking = beforeUserCreated(options, async (event) => {
    const userRecord = event.data // AuthUserRecord === UserRecord
    // userRecord.uid
    // userRecord.email

    // 1.0 validate
    if (userRecord?.email?.includes("@hotmail.com")) {
        throw new HttpsError("invalid-argument", "don't use hotmail")
    }
    // 2.0 perform block side effects
    // e.g. add a user document to the database:
    await addUserDocFor(userRecord)
    return
})
```

## Non blocking functions

The non blocking functions run _after_ a user has been created (or deleted) by Firebase Auth.

As of writing, there is no _v2_ version for the non blocking functions:

```ts
auth.user().onCreate(async (user) => {})
auth.user().onDelete(async (user) => {})
```

### example: add the user to the Firestore database (or delete it)

We read the auth user's _uid_ and act accordingly:

```ts
export const onRegisterNonBlocking = region("europe-west1")
    .auth.user()
    .onCreate(async (user) => {
        const { uid, email } = user
        // add to db
        await db.doc("users/" + uid).set({ uid, email })
        // delete from db
        await db.doc("users/" + uid).delete()
    })
```

# on Firestore and Storage events



## on Firestore events

Run Cloud functions on database events. They are non-blocking: they run after writes. As they don't prevent writes, we don't call it validation. Instead we use the term sanitization.

### sanitize data post-write

[List of Cloud Firestore triggers](https://firebase.google.com/docs/firestore/extend-with-functions-2nd-gen).

For example, _onDocumentWritten_ triggers on:

- _onDocumentCreated_
- _onDocumentUpdated_
- _onDocumentDeleted_

```ts
export const onUserWritten = onDocumentWritten("users/{docId}", (event) => {
    const docId = event.params.docId // string

    const change = event.data
    // Change<QueryDocumentSnapshot | DocumentSnapshot> | undefined

    const before = change?.before.data() // DocumentData | undefined
    const after = change?.after.data() // DocumentData | undefined
})
```

## on Storage events

### sanitize data post-upload

the user uploads a file to Firebase Storage. Sanitize data post-upload. For example:

```ts
import { onObjectFinalized } from "firebase-functions/v2/storage"

export const generateThumbnail = onObjectFinalized(async (event) => {
    const file = event.data

    // const fileBucket = file.bucket;
    // const filePath = file.name;
    // const contentType = file.contentType;
    // const metageneration = file.metageneration;
    // // Number of times metadata has been generated. New objects have a value of 1.
})
```

# Dates and Timestamps serialization



### ISO strings are the better choice

When interacting with Callable Functions, it's best to represent dates as _ISO strings_. The value and the type stay consistent when sending and receiving on the client and on Cloud functions.

In this article, we explain what happens when we send _Date_ and _Timestamp_ objects to Callable Functions or when we receive them from Callable Functions. Before being sent, both _Date_ and _Timestamp_ are serialized to JSON.

### sending _Date_ and _Timestamp_ to Callable Functions (do not use)

_Timestamp_ is a Firestore specific type and doesn't get a special treatment: it serializes to an object with _seconds_ and _nanoseconds_ (through _toJSON()_).

```ts
// on the Cloud function receiving end
type T = { seconds: number; nanoseconds: number }
```

_Date_ fields serialize to an ISO string (through _toJSON()_):

```ts
date: "2023-10-08T07:54:47.527Z"
```

When receiving in Cloud functions, we have a type difference between _RequestData_ on the client and _RequestData_ in Cloud functions.

We could manually instantiate Timestamp or Date instances, but it requires manual processing:

```ts
new Date(date) // build a Date
new Timestamp(timestamp.seconds, timestamp.nanoseconds) // build a Timestamp
```

### returning data from Callable functions

If we attempt to return a _Date_ object, it serializes to an ISO string as well, through the same mechanism.

If we attempt to return a _Timestamp_ object, it serializes to the internal representation specific to the admin SDK, which is different than the client SDK's Timestamp representation:

possible an object with _\_seconds_ and _\_nanoseconds_. We should avoid this pattern:

```ts
// on the client SDK receiving end
type T = { _seconds: number; _nanoseconds: number }
```

# Environment variables



Firebase provides a way to register and manage secrets through the CLI. We then read them from Cloud functions, both from deployed functions and from functions running locally in the emulator.

As such, we don't need to store secrets in local .env files.

## Manage secrets

### set, read and destroy secrets through the CLI

```bash
firebase functions:secrets:set ABC_API_KEY
firebase functions:secrets:access ABC_API_KEY
firebase functions:secrets:destroy ABC_API_KEY

gcloud secrets list --project <PROJECT_ID>
```

Note: the secrets are available both locally (function emulator) and for deployed functions.

### read secrets from cloud functions

We declare the secrets requirements in the function options. We then read them from `process.env`:

```ts
const options: CallableOptions = {
    // ..
    secrets: ["ABC_API_KEY"],
}

onCall<ReqData, Promise<ResData>>(options, async (request) => {
    const abcKey = process.env.ABC_API_KEY
})
```

Https functions:

```ts
const options: HttpsOptions = {
    // ..
    secrets: ["ABC_API_KEY"],
}

onRequest(options, (req, res) => {
    const abcKey = process.env.ABC_API_KEY
})
```

## .env file pattern

The .env file pattern should be only used if the CLI pattern is not available or not applicable. We set the env variables in a _.env_ file:

    ABC_API_KEY=xxx

The key is then made available to cloud functions the same way as seen above, at `process.env`, both locally and for deployed functions, as long as the key is listed in the options.

On deploy, the .env file is automatically detected and deployed along functions. See [env-variables docs](https://firebase.google.com/docs/functions/config-env?gen=2nd#env-variables)

# Debug Functions locally



### start the functions emulator

We run the functions with other emulators, or on their own:

```bash
firebase emulators:start
firebase emulators:start --import emulator-data --export-on-exit

firebase emulators:start --only functions
npm run serve
```

### invoke callable functions through the SDK

We redirect client invocations towards the emulated functions, but only on _localhost_:

```ts
if (location.hostname === "localhost") {
    // ...
    connectFunctionsEmulator(functions, "localhost", 5001)
}
```

### invoke _callable_ functions outside the client SDK

We can invoke callable functions outside the client SDK as long as the function emulator is running.

The emulator exposes them on specific URLs. We get the URLs when starting the emulators:

```
http://localhost:5001/imagetale/europe-west1/get_images
```

Callable functions can be invoked:

- directly, with a local HTTP request
- through the Firebase REPL shell.

In both cases, the request's data must be present in the _data_ key of the request's body (JSON). The _data_ key must exist.

Note: We turn off authentication requirements when calling callables outside the client SDK

### calling functions with curl

We can invoke callable functions with _curl_:

```bash
curl -H "Content-Type: application/json" \
  -d '{ "data": { } }' \
  http://localhost:5001/imagetale/europe-west1/get_images
```

### calling functions with the Firebase REPL

_functions:shell_ starts the functions emulator and an interactive CLI shell from which we invoke _callable_ functions.

```bash
firebase functions:shell
```

We provide the _data_ key and its content, which represents the request's data:

```ts
generateExample({ data: { word: "你好" } })
```

# Schedule Cron jobs



### periodic code execution: schedule a Cron job

We schedule a Cron job, with the help of Google Cloud's [Cloud Scheduler](https://console.cloud.google.com/cloudscheduler). We register a job with _onSchedule_. We set:

- the periodicity, using strings such as `every day 00:00` or `every 8 hours`.
- the timezone (IANA string), the region and the callback function:

```ts
export const updateRankingsCRON = onSchedule(
    {
        schedule: "every day 00:00",
        timeZone: "Europe/London",
        region: "europe-west1",
    },
    async () => {
        // ...
    },
)
```

The older API (v1) relied on _pubsub_ instead:

```ts
export const updateRankingsCRON = functions.pubsub
    .schedule("every 8 hours")
    .timeZone("Europe/London")
    .onRun(async (context) => {
        // ..
    })
```

Firebase

Editing and staging

Common commands

Branches

Remote

Stashing unsaved work

Other

Internals

# Overview

<div class="bookHeroImage" style="padding: 32px;margin: 8px 0;">
<svg xmlns="http://www.w3.org/2000/svg" width="292" height="92pt" viewBox="0 0 219 92">
    <defs>
        <clipPath id="a">
            <path d="M159 .79h25V69h-25Zm0 0"/>
        </clipPath>
        <clipPath id="b">
            <path d="M183 9h35.371v60H183Zm0 0"/>
        </clipPath>
        <clipPath id="c">
            <path d="M0 .79h92V92H0Zm0 0"/>
        </clipPath>
    </defs>
    <path style="stroke:none;fill-rule:nonzero;fill:#362701;fill-opacity:1" d="M130.871 31.836c-4.785 0-8.351 2.352-8.351 8.008 0 4.261 2.347 7.222 8.093 7.222 4.871 0 8.18-2.867 8.18-7.398 0-5.133-2.961-7.832-7.922-7.832Zm-9.57 39.95c-1.133 1.39-2.262 2.87-2.262 4.612 0 3.48 4.434 4.524 10.527 4.524 5.051 0 11.926-.352 11.926-5.043 0-2.793-3.308-2.965-7.488-3.227Zm25.761-39.688c1.563 2.004 3.22 4.789 3.22 8.793 0 9.656-7.571 15.316-18.536 15.316-2.789 0-5.312-.348-6.879-.785l-2.87 4.613 8.526.52c15.059.96 23.934 1.398 23.934 12.968 0 10.008-8.789 15.665-23.934 15.665-15.75 0-21.757-4.004-21.757-10.88 0-3.917 1.742-6 4.789-8.878-2.875-1.211-3.828-3.387-3.828-5.739 0-1.914.953-3.656 2.523-5.312 1.566-1.652 3.305-3.305 5.395-5.219-4.262-2.09-7.485-6.617-7.485-13.058 0-10.008 6.613-16.88 19.93-16.88 3.742 0 6.004.344 8.008.872h16.972v7.394l-8.007.61"/>
    <g clip-path="url(#a)">
        <path style="stroke:none;fill-rule:nonzero;fill:#362701;fill-opacity:1" d="M170.379 16.281c-4.961 0-7.832-2.87-7.832-7.836 0-4.957 2.871-7.656 7.832-7.656 5.05 0 7.922 2.7 7.922 7.656 0 4.965-2.871 7.836-7.922 7.836Zm-11.227 52.305V61.71l4.438-.606c1.219-.175 1.394-.437 1.394-1.746V33.773c0-.953-.261-1.566-1.132-1.824l-4.7-1.656.957-7.047h18.016V59.36c0 1.399.086 1.57 1.395 1.746l4.437.606v6.875h-24.805"/>
    </g>
    <g clip-path="url(#b)">
        <path style="stroke:none;fill-rule:nonzero;fill:#362701;fill-opacity:1" d="M218.371 65.21c-3.742 1.825-9.223 3.481-14.187 3.481-10.356 0-14.27-4.175-14.27-14.015V31.879c0-.524 0-.871-.7-.871h-6.093v-7.746c7.664-.871 10.707-4.703 11.664-14.188h8.27v12.36c0 .609 0 .87.695.87h12.27v8.704h-12.965v20.797c0 5.136 1.218 7.136 5.918 7.136 2.437 0 4.96-.609 7.047-1.39l2.351 7.66"/>
    </g>
    <g clip-path="url(#c)">
        <path style="stroke:none;fill-rule:nonzero;fill:#f03c2e;fill-opacity:1" d="M89.422 42.371 49.629 2.582a5.868 5.868 0 0 0-8.3 0l-8.263 8.262 10.48 10.484a6.965 6.965 0 0 1 7.173 1.668 6.98 6.98 0 0 1 1.656 7.215l10.102 10.105a6.963 6.963 0 0 1 7.214 1.657 6.976 6.976 0 0 1 0 9.875 6.98 6.98 0 0 1-9.879 0 6.987 6.987 0 0 1-1.519-7.594l-9.422-9.422v24.793a6.979 6.979 0 0 1 1.848 1.32 6.988 6.988 0 0 1 0 9.88c-2.73 2.726-7.153 2.726-9.875 0a6.98 6.98 0 0 1 0-9.88 6.893 6.893 0 0 1 2.285-1.523V34.398a6.893 6.893 0 0 1-2.285-1.523 6.988 6.988 0 0 1-1.508-7.637L29.004 14.902 1.719 42.187a5.868 5.868 0 0 0 0 8.301l39.793 39.793a5.868 5.868 0 0 0 8.3 0l39.61-39.605a5.873 5.873 0 0 0 0-8.305"/>
    </g>
</svg></div>

### traditional save patterns without git

The traditional save pattern is to store a file in-place or to a new file.

Saving in place is destructive: it does not preserve the old version.

Saving to a new file is safe, but leads to another challenge: managing multiple versions, their names, the storage and the retrieval, which is cumbersome and error-prone.

### software source code specifics

Software source code usually consists of a tree of files that, together, make a whole unit. Compiling the software usually requires to have the whole tree available as-is on the filesystem.

As such, an actionable snapshot is one that comes as a whole.

The naive way to store snapshots is to store the whole file tree for any given file change. This method has a heavy and inefficient storage footprint, due to spreading identical files across snapshots.

### what we want from a versioning software

We want an approach that is more efficient in terms of storage: the snapshots should not be stored as-is, but instead be reconstructed on-demand, with files being fetched from a central storage. The software should keep track of the files that a given snapshot relies on.

We want to conveniently browse and load old snapshots or snapshots from alternative development branches.

We also want snapshots to come with metadata: their date, their unique ID, and the description of changes they bring (commit message).

### lightweight snapshot: a declarative list of files

We have the snapshot as a declarative list of files it is comprised of, like a shopping list.

In this pattern, the files may live anywhere. This allows files to be referred to by any snapshot, and to be stored only once.

The software may reconstruct the snapshot based on the list: the software fetches the files from the storage and builds a snapshot mirror.

### editing area

The local directory where we make changes is called the `working directory` or `working tree`.

Most of the time, it should start as a mirror of the latest snapshot, allowing to work on changes and submit a new snapshot for commit.

Sometimes, it will instead mirror an old snapshot, so that we may run the snapshot as it was, or to fork away from that snapshot onwards.

### other terminology

to commit means to intentionally save a snapshot. By extension, we may refer to a snapshot itself as a commit. In git internals, a commit is the file that stores all the file dependencies and the metadata related to a given snapshot.

The `staging area`, also called the `index`, is a tentative snapshot, on that is ready to be committed. See _Editing and staging_.



# Editing and staging

### separation of concern: working directory and staging area

We keep the working directory and the staging area (index) separate to acknowledge their different role.

### the role of the working directory

The working directory is a playground where changes are not saved, good for exploration and iteration. Its content has no influence on what is saved when we perform a commit.

### terminology

This allows us to have files that we don't commit yet or ever: _untracked_ files. If the file is a modified version of one that was committed before, and that it is not staged yet, we call it _modified_.

When files are added to the staging area, they cease to be _untracked_ or _modified_: they become _staged_.

### staging area: granularity and storage

The staging area determines what is saved on commit. Having some granularity instead of saving the whole working tree has benefits:

- We may select related changes and commit them as a group.
- We may technically save different portions of a file at a time.

Besides, we may use the index as a temporary storage, in a manner similar of saving checkpoints: This allows to store one version and keep iterating on it, with the ability to revert to the checkpoint if needed.

This is possible because the index is similar to a commit: it has its own list of files, which live in the storage area, and that are decoupled from the working tree.



# Common commands

the standard workflow is as follows:

- make some changes to one or more files in the working directory
- select one or more changes, put them in the staging area
- save the staging area as a commit.

## standard flow

### stage files: working-directory to index

`git add` adds one or more files to the staging area. It affects both _untracked_ files and _modified_ files, turning them into _staged_ files.

```bash
git add .
git add -u
```

We may exclude _untracked_ files from staging with `-u`. A more permanent solution is to add them to `.gitignore`.

### commit: index to commit

Save the staging area as a new commit. It has no effect over the working directory:

```bash
git commit -m "..."
```

We may edit the last commit message with `--amend`. This does not create a new commit.

```bash
git commit --amend -m "an updated commit message"
```

Note: the `-am` flag is not a shortcut for both `git add .` and `git commit -m ''`, since it does not add _untracked_ files.

```bash
git commit -am "adding and committing modified files"
```

## reverting to the last commit

The last commit is commonly represented by `HEAD`.

### commit to working-directory: reset the working-directory.

we use `restore` and set the `--source` to HEAD.

```bash
git restore --source=HEAD --worktree  .
git restore --source=HEAD .
```

old syntax

```bash
git checkout HEAD   -- . 				# the last commit
git checkout v1.2.3 -- .      # tag v1.2.3
git checkout stable -- file   # stable branch
git checkout origin/master -- file  # upstream master
git checkout HEAD^ -- file          # the version before the last commit
```

### commit to working-directory AND index.

We aim to revert both the index and the working directory to the commit version.

It does not affect or remove untracked files, since they are ignored by git.

```bash
git restore --source=HEAD --staged --worktree .

git reset --hard
```

### commit to index: reset the staging area

We may revert the staging area to the clean state of the previous commit. The working tree is unaffected.

We use the _restore_ command, with the _staged_ flag.

```bash
git restore --staged . # tested
git reset .
```

If we are before the first commit, we may remove content from the staging area:

    git rm --cached file
    git reset

## reverting to the index version

### index to working-directory: go back to the index checkpoint

We may restore the worktree from the index. This may restore a checkpoint or the last commit, depending on the content of the staging area.

The `restore` and `checkout` command implicitly restore the worktree from the staged area. We may make it more explicit by setting flags.

```bash
git restore .
git restore --worktree . #same
git restore file
```

```bash
git checkout .
git checkout main.js
```

## reverting to older commits

### revert the current branch to a previous commit

Restaurer la version de travail, la version staged et la version
sauvegardée depuis la sauvegarde précédente nommée explicitement ou
relativement par le nombre de commit depuis cette sauvegarde.

revenir au commit spécifié explicitement.

```bash
git reset --hard 2bje9dlhash
```

revenir au commit à une distance de N par rapport au dernier commit, ici
l'avant dernier commit.

```bash
git reset --hard HEAD^1
```

## other commands

### remove untracked files

delete untracked files

```bash
git clean -fd
```

delete untracked files and files present but ignored by git

```bash
git clean -fdx
```

dry run

```bash
git clean -fdn
git clean -fdxn
```



# Branches

### a line of commits and the last commit on a line

A list of commits can be seen as a line in the sense of a continuous list of snapshots that follow each other. Technically, each commit keeps a reference to its parent (the former commit), so that we may reconstruct a whole line from a given commit.

We may conceptualize a branch as a line of a commits that lead to a tip commit.

There are as many distinct theoretical branches as there are commits, and we may have several actual branches pointing to the same commit.

All it takes to create a branch is to pick a name and decide what commit it points to. This commit becomes the current tip of the branch.

Branches are independent from each others: they allow to work in isolation. When we add a commit, the active branch is updated to point to the new commit, while others are untouched.

### branches that live on the same line: fast-forward compatible

We may say that two branches live on the same line when the longer branch is the continuation of the shorter branch. The tip of the longer branch is a descendant of the tip of the short branch.

To fast forward a branch is to bring it closer to, or at the same point than a longer branch that lives on the same line. Technically, we make it point to a more recent commit on the line.

while the git command we use is called _merge_, there is no graph merge during a fast-forward.

### branches that have forked: eligible for a merge commit

One branch has forked from the other one. The last commit they have in common is the common ancestor. The merge commit is one that aims to merge the paths coming from two parents. As such, it is a special commit that points to two parents instead of one.

Git compares files across the two parents and, when they are different, checks if one of them is _stalled_, aka has not changed since the last common ancestor. In that case, it favors the one that has received work, as it assumes the merge intends to make use of such work.

If both paths have worked on the ancestor version to change it, the merge cannot pick one version on its own. It asks the developer to resolve the difference between the two parents.

### add the merge commit to the receiving branch

Once the merge commit has been created, the merge process doesn't merge the two branches into one, neither does it make both branches point to it.

Instead, the merge commit is only added to the _receiving_ branch. The receiving branch is now "aware" of the two paths that led to the merge commit.

The other branch stays as-is. It is eligible for fast forward toward the receiving branch.

### merge one branch (ex:dev) to current (ex:main) (repetition)

We first compare the two branches: the receiving branch (current), and
the giving branch.

If the receiving branch is a parent of the giving branch, that is, it
has not drifted away because it didn't do any commit on its own, then we
can simply fast forward the receiving branch to the state of the giving
branch, making them point to the same commit.

If the receiving branch has done at least one distinct commit, it means
there was an actual fork, and a merge commit is required, to integrate
the branch that has forked, and to preserve the fact that there was a
fork. The merge commit only occurs on the receiving branch.

For example, we merge dev into main. dev is unaffected. main has a merge
commit.

## commands

### list branches

```bash
## list branches
git branch
## includes remote-tracking branches
git branch -a
```

### create, rename, delete branch commands

creating a branch does not switch to it.

```bash
git branch dev
git branch -m master main
git branch -d dev
```

### branch switching

switching to a branch means to have HEAD pointing to the branch, which points to a commit. The idea of switching to a commit is to get a clean working directory and index that match this commit, so we may start working from this snapshot.

```bash
git switch dev
```

### switching to a branch that comes from a remote

if the remote branch such as _origin/dev_ does not have a matching local branch, the git switch command may create the _dev_ local branch and switch into it.



# Remote

### instances and the canonical repository.

A remote repository is an instance of the repository that lives at another location.

There is no built-in hierarchy between instances. When there is a conflict, it's up to users to resolve it.

We use a pattern that sets one instance as the source-of-truth, with some flexibility when it needs to be corrected. We name it the _canonical repository_.

In practice, we put the canonical repository on a server known by all team members. Each member pushes changes to it and pulls changes from it.

For example, a member sets up a repository and publishes it to a host such as Github. The hosted repository becomes the _canonical repository_. Then, members clone the repository. _Cloning_ downloads the repository and pre-configures it to be linked with the _canonical repository_.

### remote-tracking branch

the remote-tracking branch mirrors a branch that lives on a remote repository, usually the canonical repository. As a faithful mirror, it is read-only, and only changes through a network call that signals changes.

we may poll the remote repository with `git fetch`. If updates are found, Git downloads the related commits and add them to the remote-tracking branches. We may inspect them like any other branch: we may log the commits and check the differences.

```bash
git log origin/main
git diff main origin/main
```

We may then merge the remote-tracking branch into the local-only one:

```bash
git merge origin/main
```

_git pull_ is a shortcut for _git fetch_ and _git merge_.

### remote

As a Git technical term, a _remote_ is a configured reference to a remote repository. We setup a remote to be able to push and pull from it.

We add a remote through its URL, and give it an alias name for convenience. By convention, we use _origin_ for the main repository remote.

```bash
git remote add origin https://github.com/user333/helloworld.git
```

We may list remotes and show information for a given one. It's usually only _origin_.

```bash
git remote show
git remote show origin

## remote origin
##   Fetch URL: https://github.com/user33/abc.git
##   Push  URL: https://github.com/user33/abc.git
##   HEAD branch: main
##   Remote branch:
##     main tracked
##   Local branch configured for 'git pull':
##     main merges with remote main
##   Local ref configured for 'git push':
##     main pushes to main (up to date)
```

### mutate a remote's URL

example: change the URL that _origin_ refers to

```bash
git remote set-url origin git@github.com:user33/abc.git
```

### merge the changes coming from remote

this is what happens when we do git pull (fetch + merge): the _fetch_
updates _origin/main_, then the merge applies a fast forward so that
main and origin/main point to the same commit.

```bash
git merge origin/main
```

### merge a branch into main

```bash
git merge <branch-name>
git merge dev
```

## clone: download and expand the .git directory

### download

a clone downloads the .git directory.

    https://github.com/mantinedev/mantine.git

we may clone a stripped-out version of the .git directory, one that
contains fewer files.

For example, we ask the files needed by the last commit, and not the
others. This is called a shallow clone.

We specify the depth, to target only the n-last commits.

```bash
git clone --depth 1 https://github.com/mantinedev/mantine.git
git clone --depth 1 [--branch master] https://github.com/mantinedev/mantine.git
```

### expand

the clone automatically expands the latest commit files into the working
directory.

## branches and remote

### push a branch that does not exist yet on the remote repository

Given that the remote repository doesn't have our local branch, we also don't have a remote-tracking branch that is supposed to track this branch on the remote. As such, we cannot set up an upstream just yet, because doing so requires binding a local-only branch to a remote-tracking branch.

Instead, we must first push the branch to the remote repository. If it is successful, we get the remote-tracking branch, and Git may now bind the branch to the remote-tracking branch, configuring it as the upstream.

We do it with one command: the `push` command, where we specify which _remote_ we are pushing to, which branch we are pushing, and that we want Git to make the upstream binding if the push was a success

```bash
git push -u origin 2024
```

### delete a branch on the remote repository

push is because it's an update to the remote repo.

```bash
git push origin --delete 2024
```

### indicate match between current branch and remote-tracking branch

```bash
git branch --set-upstream-to origin/my_branch
git branch -u origin/my_branch
```

### prune remote-tracking branches

We may have deleted some branches on the remote, and we want our repository to stop mirroring them:

```bash
git fetch --prune
```



# Stashing unsaved work

### dirty working tree

The working tree is dirty when it has _modified files_. They may represent unsaved work. _Untracked files_ live outside of Git, but may also represent unsaved work.

the _modified files_ that we added to the index became _staged files_. They also represent unsaved work.

There are a few scenario where Git has to clear up both the working tree and the index, to replace them with the content from another commit. This may occur when switching to a branch that points to another commit, or when merging some remote branch into our current one. (this does not occur when creating a branch because it keeps pointing to the current commit, keeping the current changes relevant)

The straightforward solution is to save the pending work into a new commit to make the working directory and index clean, and then perform the operation mentioned above.

### stashing and popping

In the case where we _don't want_ to create a commit, but we want to preserve the work that lives in the working tree and the index, we may ask Git to `stash -u` the changes. Under the hood, Git creates a hidden commit for the working tree and one for the index.

Later, we may reverse the operation, bringing back the unsaved work to the working tree and the index, with `pop --index`.

```bash
git stash
git stash -u # include the untracked files
```

Restore the working directory and staging area, assuming we are back on the correct branch. the --index flag restores the staging area as well.

```bash
git stash pop --index # if it worked without conflict

git stash pop --index
git stash drop # if conflict happened and has been solved

git stash apply --index # apply never drops the stash
git stash drop
```

### conflict resolution on pop

When popping the unsaved files back to the working tree, there may be a conflict. The conflict resolution is the same as the one for merge conflicts. If it cannot solve the conflict itself, it will expose the incompatible changes in the files with visible marks to let the developer pick one. Similar for merge conflicts, the developer edits the file and signals it as resolved by performing a `git add` on the file.

As Git is conservative, it does not clear the stash if a conflict was detected. After we have resolved the conflict, we may have to clear the stash manually.

advanced: If we attempt to pop back a file from the index into an index that has a distinct version that also received work, it will fail completely, since the manual resolution is not possible for files that are in the index.

###



# Other

edit the files without editing the message

    git commit --amend --no-edit

### example

    git init
    git add .
    git commit -m "initial commit"
    git remote add origin https://github.com/s3/aw33.git
    git push -u origin master

### diff

    git diff
    git diff --staged

The default diff is the one between the working tree and the staging area.

Once changes are staged, we may check the diff between the staging area and the last commit instead.

### information about latest commit

we may show information about a commit, including the diff, with the git
show command. It shows information about the last commit by default.

    git show

### prune .git folder, prevent some safeguards

### clean : supprimer aussi les untracked files et folders

    git clean -df

supprime les untracked files et directories. En effet, git checkout . ne
permet pas de supprimer les fichiers et directories qui sont untracked,
ramene a leur ancienne version seulement les fichiers tracked.

### log commits, forks and merges

we log the commits of the current branch

    git log

we may display the forks and merge commits

    git log --graph --oneline

### head

Head is which commit the working tree is coming from.

We change the head by checking out a specific commit.

When we check-in a commit that is not tracked by any branch, we say the
head is detached, probably meaning detached from any branch.



# Internals

### the .git directory serves as the git repository

In Git terminology, the git repository is the `.git` directory managed by git. It is a hidden directory that lives at the root of the project. It stores all versioning data.

Because the directory stores all the project's data, we sometimes conflate it with the project directory itself, the one that lives locally and that contains both the working tree and the git repository proper.

### enable git versioning in a project

The git init command creates the .git repository and enables git commands.

```bash
git init
```

### .git directory content

files and directories

    COMMIT_EDITMSG
    FETCH_HEAD
    HEAD
    ORIG_HEAD
    config
    description
    index
    packed-refs

    hooks/
    info/
    logs/
    objects/
    refs/

### project specific configuration

the configuration file lives at .git/config

```bash
open .git/config
```

### per user configuration

We may configure git at the user-level on a given computer. The configuration file is `.gitconfig` and lives in the home directory

```bash
code ~/.gitconfig
code ~/.gitattributes

git config user.name
git config user.email

git config user.name "John"
git config user.email "a@b.co"
```


JS Date API introduction

Formatting dates

Format dates with Luxon

Format dates with Intl

Other formatting

Parsing Calendar components

Format Durations with Luxon

Format Durations with Intl

Relative time

# Overview

### terminology

- An instant is a point in time. We sometimes use the term timestamp.
- A duration is a quantity of time, and a distance between two instants.
- In the context of calendar components, _date_ and _time_ have specific meaning:
    - _date_ refers to calendar components from year to day (_year_, _month_ and _day_), e.g. `2026-06-30` or `YYYY-MM-DD`. It matches the Temporal's _PlainDate_.
    - _time_ refers to components from hours to milliseconds (or even nanoseconds), e.g. `08:15:00.001` or `HH:mm:ss.SSS`. It matches the Temporal's _PlainTime_.

### APIs

JavaScript offers severals ways to work with dates, time and durations:

- The `Date` API
- The `Temporal` API (ES2026)
- The `Intl` API

### libraries

In this book, we cover the [Luxon](https://github.com/moment/luxon/) library as it supports time zones whereas JS Date doesn't. Luxon also provides formatting capabilities that neither Date and Temporal provide.



# JS Date API introduction

### instants

JS _Date_ objects represent and store instants (aka dates) as millisecond timestamps. The timestamp is the number of milliseconds since Jan 1st, 1970 at 00:00:00 UTC, aka the Unix Epoch.

### read the millisecond timestamps

We read the timestamp from a date object:

```ts
d_2021.getTime() // 1,609,459,200,000 (ms)
```

We can read the current timestamp:

```ts
Date.now() // 1,777,109,775,765 (ms)
```

### build a Date from a timestamp

We build a date from a given timestamp (or from the current one)

```ts
new Date(1_627_541_982_738) // 2021-07-29T06:59:42.738Z
new Date() // from current timestamp
```

### compare dates

The difference between two timestamps, considered as an absolute value, represent the amount of time between both dates.

```ts
d_1971.getTime() - d_1970.getTime() // 31,536,000,000 (ms)
```

Note: if we try to subtract dates directly, it fails in TypeScript.

We can use the comparison operators on dates to check for posteriority:

```ts
d_2021 > d_2020 // true
```

### (misc) console built-in date formatting

JavaScript consoles don't log dates as milliseconds as it's unreadable. They log dates in a calendar format:

- The Node.js REPL use the standard ISO 8601 format (in the UTC time zone).
- The browsers' console uses a lengthier format, using the device time zone.

```ts
new Date(1_627_541_982_738)
// 2021-07-29T06:59:42.738Z // Node.js
// Thu Jul 29 2021 08:59:42 GMT+0200 (Central European Summer Time) // Chrome
```



# Formatting dates



### calendar components

The main way to format dates is to express them with appropriate calendar components, correct units and the correct time zone.

### formatting APIs

We can format dates using _Intl_ or _Luxon_.

### the need for a timezone

An instant must be combined with a time zone to be translated to calendar components.

### lack of a time zone in a JS Date

A JS _Date_ doesn't store a time zone: we must read it from another source.

When the time zone is omitted, some formatting helpers fall back to the _host machine's time zone_, but:

- The host machine time zone doesn't necessarily match the event's time zone. In this case, it becomes impossible to read the event's local date and time on which it occurred.
- Even if the time zones match, there is no guarantee that the machine's time zone will remain fixed, thus it risks breaking the reading later on.

# Format dates with Luxon



Luxon uses _DateTime_ as its main API to work with dates. We first instantiate a DateTime instance.

### (preliminary) instantiate a _DateTime_ instance

We can instantiate a _DateTime_ from:

- a JS Date
- an ISO string
- a milliseconds timestamp

```tsx
DateTime.fromJSDate(date, { zone: "Europe/London"; });
DateTime.fromISO(isoString, { zone: "Europe/London"; });
DateTime.fromMillis(ms, { zone: "Europe/London"; });
```

### format calendar component(s) with a format string

Date components format strings:

```ts
dt.toFormat("yyyy") // "2026"
dt.toFormat("yy") // "26"

dt.toFormat("MMMM") // "January"
dt.toFormat("MMM") // "Jan"
dt.toFormat("MM") // "01"
dt.toFormat("M") // "1"

dt.toFormat("dd") // "09"
dt.toFormat("d") // "9"

dt.toFormat("EEEE") // "Friday"
dt.toFormat("EEE") // "Fri"
```

Time component format strings:

```ts
dt.toFormat("HH:mm:ss") // "08:05:05"

dt.toFormat("H 'hours'") // "8 hours"
dt.toFormat("m 'minutes'") // "5 minutes"
dt.toFormat("s 'seconds'") // "5 seconds"

dt.toFormat("s.SSS's'") // "5.123s"

// 12 hour format
dt.toFormat("h:mm a") // "8:05 AM"
```

### add literal text

We can add literal text safely with single quotes:

```ts
dt.toFormat("MMMM d 'at' HH:mm") // "June 19 at 14:30"
```

Some characters such as slashes can be added unquoted as they don't clash with date and time tokens:

```ts
dt.toFormat("yyyy/MM/dd") // "2026/06/19"
```

### ISO formatting

_DateTime_ supports three ISO string helpers:

```ts
dt.toISO() // "2026-02-13T19:50:15.123+01:00" <-- Includes offset
dt.toISODate() // "2026-02-13"
dt.toISOTime({ includeOffset: false }) // '07:34:19.361'
```

### (optional) read individual calendar components

We can read the calendar components, as _numbers_, or sometimes as _strings_:

```ts
const dt = DateTime.fromJSDate(date, { zone: "Europe/London" })

// Getters
dt.zoneName // 'Europe/London'
dt.year
dt.month // 1-12
dt.day // 1-31
dt.hour // 0-23
dt.minute // 0-59
dt.second // 0-59
dt.millisecond

dt.weekdayLong // 'Monday', 'Tuesday', etc.
dt.monthLong // 'January', 'February', etc.
```

For destructuring, we convert to an object beforehand:

```ts
// Make plain object and destructure
const { year, month, day, hour, minute, second } = dt.toObject()
```

# Format dates with Intl



### overview

_Intl_ relies on creating and using formatters, providing options and a locale:

```ts
const formatter = new Intl.DateTimeFormat("en-US", options)

formatter.format(new Date(1781860473660)) // "June 19, 2026"
```

### options

An options object sets the format for the calendar components we want to include. If a component is left out (or is set to _undefined_), it is omitted from the formatted output:

```ts
const options: Intl.DateTimeFormatOptions = {
    timeZone: "America/Los_Angeles",
    year: "numeric", // "2026"
    month: "long", // "June"
    day: "numeric", // "19"
}
```

Note: We specify the time zone in the formatter options.

### locale support

_Intl_ supports a locale to customize the format. It is sometimes required. It is not part of the options object: we provide it separately.

The locale follows the _BCP 47_ format, e.g. _en-GB_ or _fr-FR_.

```ts
const formatter = new Intl.DateTimeFormat("en-GB", options)
```

If _undefined_, _Intl_ defaults to the host machine's locale.

### create a custom formatter

Create a fully-fledged, reusable formatter:

```ts
const formatter = new Intl.DateTimeFormat("fr-FR", {
    // timeZone: "Europe/Paris",
    // month: "long",
    // day: "numeric",
    // hour: "2-digit",
    // minute: "2-digit",
})

formatter.format(date) // "19 juin à 11:14"
```

### use a built-in formatter with options

Built-in formatters use _Intl_ under the hood: the options object is of the same format:

```ts
date.toLocaleDateString("fr-FR", options) // "19 juin à 11:14"
```

### locale-aware built-in formatters on Date instances

Note: those function work with a locale and an optional options object with the timezone.

Using _undefined_ for the locale means to use the host's locale:

```ts
// const options = { timeZone: "America/Los_Angeles" }
// device locale: en-US
// devide time zone: Europe/Paris

date.toLocaleString("fr-FR") // 29/01/2022, 21:52:08
date.toLocaleString("fr-FR", options) // 29/01/2022 12:52:08
date.toLocaleString(undefined) // 1/29/2022, 9:52:08 PM
date.toLocaleString(undefined, options) // 1/29/2022, 12:52:08 PM

date.toLocaleTimeString("en-US", options) // 12:52:08 PM
// ... other variants

date.toLocaleDateString("en-US", options) // 1/29/2022
// ... other variants
```

### (advanced) list of options

see the list of [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) (_Intl.DateTimeFormatOptions_).

```ts
type Intl.DateTimeFormatOptions = {

 // shortcut options
 dateStyle: 	'full' | 'long' | 'medium' | 'short';
 timeStyle: 	'full' | 'long' | 'medium' | 'short';

 // granular options
 weekday: 	'long' | 'short' | 'narrow';
 year: 	'numeric' | '2-digit';
 month: 	'numeric' | '2-digit' | 'long' | 'short' | 'narrow';
 day: 		'numeric' | '2-digit';
 hour: 	'numeric' | '2-digit';
 minute: 	'numeric' | '2-digit';
 second: 	'numeric' | '2-digit';
 fractionalSecondDigits: 1 | 2 | 3;

 timeZoneName: 'long' | 'short' | 'shortOffset' | 'longOffset' | 'shortGeneric' | 'longGeneric';
 timeZone: string;

 hour12: boolean | 'h11' | 'h12' | 'h23' | 'h24';
};
```

# Other formatting



### JS helpers that rely on the host timezone (avoid)

Those helpers ignore the timezone in which the event happened (which isn't stored by the JS Date). Instead, they display the event as it reads in the host machine timezone.

For example, an event that occurred at _midnight_ in Paris is read as 7*AM* with no mention of _midnight_ at all when the device is in the China timezone (_getHours()_ on a China-based machine reads as _7_.

### pre-formatted strings (relying on the host machine timezone)

Note: those helpers don't accept a locale or an options object with a timezone.

```ts
date.toString()
// Sun Jun 12 2022 11:44:53 GMT+0200 (Central European Summer Time)

date.toDateString()
// Sun Jun 12 2022

date.toTimeString()
// 11:44:53 GMT+0200 (Central European Summer Time)
```

### to UTC timezone ISO string

ISO8601 is an international standard. It indicates both the date component and the time component. It may provide the timezone.

```ts
birthDate.toISOString() // 2015-06-18T11:13:00.000Z
Date.parse("2015-06-18T11:13:00.000Z")
```

### (optional) read calendar components

```ts
// the event occured on January 1st 2025, at 00:00 AM (Paris), device in China
birth.getFullYear() // 2025
birth.getMonth() // 0 (January)
birth.getDate() // 1 (for 1st)

birth.getHours() // 7
birth.getMinutes() // 0

// the UNIX Epoch instant
// Device in (Europe/Paris)
new Date(0).getHours() // 1
```

# Parsing Calendar components

A timezone is required to disambiguate the calendar components.

### derive JS Dates from timezone aware objects

From a Luxon object:

```ts
const dt = DateTime.fromObject(
    {
        year: 2015,
        month: 6,
        day: 18,
        hour: 13,
        minute: 13,
    },
    {
        zone: "Europe/Paris",
    },
)

const birthDate = dt.toJSDate()
```

From a Temporal _ZonedDateTime_ object (through milliseconds conversion):

```ts
const dt = Temporal.ZonedDateTime.from({
    year: 2015,
    month: 6,
    day: 18,
    hour: 13,
    minute: 13,
    timeZone: "Europe/Paris",
})

const birthDate = new Date(dt.toInstant().epochMilliseconds)
```

### derive the JS date from an ISO string

With an UTC offset in the date time string. This is worse than providing a timezone because it requires knowledge about the offset of the location at this date.

```ts
new Date(isoString)

new Date("2015-06-18T13:13+02:00") // offset ISO, minutes granularity
new Date("2015-06-18T13:13:00+02:00") // offset ISO, seconds granularity
new Date("2015-06-18T11:13:00.000Z") // UTC ISO (Z)
```

### helpers that assume UTC

from a date-only ISO string:

```ts
new Date("2015-06-18") // assumed to be UTC
```

### helpers that assume host timezone (brittle, do not use)

The helpers assume the local timezone:

```ts
const birth = new Date(2015, 5 /* June */, 18, 13, 13)
new Date("2015-06-18T13:13:00")
```



# Format Durations with Luxon



Luxon uses _Duration_ to manage durations.

### instantiation

The unit(s) we pick for instantiation determines the default unit(s) being used:

```ts
Duration.fromMillis(1_000_000)
// dur.toHuman() // '1000000 milliseconds'

Duration.fromObject({ hour: 36 })
// dur.toHuman() // '36 hours'
```

We can build a duration from two _DateTime_ instances, and set the units being used:

```ts
const dur = dt2.diff(dt1, ["years", "months", "days"])
// dur.toHuman() // "3 years, 2 months, 14 days"
```

### control the unit(s)

We configure the duration units directly on the duration object, controlling subsequent outputs:

- `rescale()` automatically determines which units to use. It eagerly uses the higher magnitude units, then sets them as the current units:

```ts
// dur.toHuman() // '1000000 milliseconds'
dur.rescale().toHuman() // '16 minutes, 40 seconds'
```

- `shiftTo()` aims to set the units imperatively, and set them as the current units:

```ts
// dur.toHuman() // '1 day, 12 hours'
dur.shiftTo("hours", "minutes").toHuman() // '36 hours, 0 minutes'
dur.shiftTo("minutes").toHuman() // '2160 minutes'
```

### output the configured duration

`toHuman()` outputs a human-readable duration. It uses the units as configured:

```ts
// 1.0 configuration
// 2.0 output
dur.toHuman() // '1 day, 12 hours'
dur.toHuman({ listStyle: "long" }) // '1 day and 12 hours'
```

# Format Durations with Intl



Format durations with [_Intl.DurationFormat_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat) (limited).

# Relative time

We use methods from Luxon's _DateTime_ instances.

### describe the distance in time from now

A relative time describes how far we are, as of now, from an event that happens in the past or in the future. It is a duration relative to now. We focus on the duration, such as _3 hours ago_, or _in 2 minutes_.

```ts
dt.toRelative() // "4 hours ago"
dt.toRelative() // "in 2 days"

dt.toRelative({ style: "short" }) // "4 hr. ago"
dt.toRelative({ style: "narrow" }) // "4h ago"
dt.toRelative({ unit: "seconds" }) // "300 seconds ago"
dt.toRelative({ unit: "years" }) // "1 year ago"
dt.toRelative({ round: false }) // "4.5 hours ago"
dt.toRelative({ base: anchor }) // "5 years ago"
```

### prioritize the calendar aspects, day granularity, day and month difference

We describe where the event takes place in the calendar relative to now. It uses calendar date components, with precision capped to day difference, such as _today_ or yesterday.

```ts
dt.toRelativeCalendar() // "today"
dt.toRelativeCalendar() // "yesterday"
dt.toRelativeCalendar() // "tomorrow"
dt.toRelativeCalendar() // "2 days ago"
dt.toRelativeCalendar() // "last month"
```


Date & Time

Property list files

Application bundle

Application's persisted data

Launch processes automatically

Default directories and files

# Overview

### understand the macOS design choices

We discuss macOS conventions, patterns and defaults, and try to understand the design choices behind them.



# Property list files

A `.plist` file (Poperty List) commonly stores a set of user-preferences or some metadata about an app. It is a list of key-values.

The data's format is either binary or XML.

We may view or edit data with Xcode or `plutil`. We may use a text editor for XML ones.

```bash
plutil -p Info.plist
plutil -p "/Applications/Discord.app/Contents/Info.plist"
```

we may use `file` to detect if it's binary or XML:

```bash
file Info.plist
## Info.plist: XML 1.0 document text, ASCII text
```



# Application bundle



A pattern where we bundle the executable along with supporting files in a directory that looks like the application itself, at least in the Finder, as it has an `.app` suffix and as it comes with special behaviour and appearance:

-   The double-click runs the program instead of opening the directory
-   Finder shows the application's icon instead of a directory icon.

The content is semi-standardized. It includes

-   the icons
-   the internationalization strings
-   metadata about the app
-   frameworks and libraries, separated from the executable.

```bash
ls -1p "/Applications/Google Chrome.app/Contents/"

Frameworks/
Library/
Resources/
_CodeSignature/
MacOS/

Info.plist
PkgInfo
```

Such content should be treated as read-only, as tampering it triggers a signature change and security measures that prevent the executable from running.

The application's dynamic data and preferences are stored outside the bundle.

# Application's persisted data



The `Library` directory, located in the user's directory, helps to store data and preferences on behalf of applications.

While it has many directories, the ones that applications should use are as follows:

```
~/Library/Application\ Support/
~/Library/Caches
~/Library/Preferences
```

### preferences

The `Preferences` directory stores lightweight user-preferences files related to a given program. They represent persisted user-specific settings. For example, _com.apple.dock.plist_ stores the _Dock_ settings.

```bash
ls ~/Library/Preferences/

com.microsoft.VSCode.plist
com.blizzard.diablo3.plist
com.apple.dock.plist

plutil -p ~/Library/Preferences/com.apple.dock.plist
```

### application support

`Application Support` is the general purpose storage area where each application may persist arbitrary data, such as databases, downloaded content, or extensions.

### caches

`Caches` stores cached data on behalf of applications. Those are usually artifacts produced by network fetches, which cache the network responses to keep them available across runs.

# Launch processes automatically

### register a process for automatic launch

Applications (or simple processes) may request the OS to automatically launch them at boot-up or at user-login.

Boot-up items start before login, for critical services that should run as soon as possible and regardless of the user.

Login items start on user login, and may launch applications automatically.

### traditional registration process

We craft a `plist` file that identifies a process and provides some settings such as the launch arguments. We then place it in a hardcoded directory.

We place it in `/Library/LaunchDaemons` if it has to start on boot-up. We place it in either `/Library/LaunchAgents` or `~/Library/LaunchAgents` if it has to start on user login.

macOS manages a distinct database to keep track of which item has been disabled from the OS login-items settings.

```bash
open /Library/LaunchDaemons
open /Library/LaunchAgents
open ~/Library/LaunchAgents

sfltool dumpbtm

launchctl print-disabled user/$(id -u)
```

### modern registration process

applications are now encouraged to store the `plist` files inside their bundles and register them through a macOS API. This ends the pattern of having `plist` files outside of their bundles.

```
MyApp.app/
 └── Contents/
      ├── Info.plist
      ├── MacOS/
      │    └── MyApp  (The main executable)
      └── Library/
           └── LaunchAgents/
                └── com.myapp.helper.plist
```



# Default directories and files

### disk root directory

The root location aka `/` contains:

-   the UNIX-style directories aka `bin`, `usr`, and more. The `etc`, `tmp` and `var` directories are aliases: they live in `private/`.
-   the user-facing folders such as `Users`, `Applications`, `Library`, `System` and `Volumes`.

```
┌── Applications/
├── Library/
├── System/
├── Users/
├── Volumes/
│
├── bin/
├── cores/
├── dev/
├── etc/
├── home/
├── opt/
├── private/
├── sbin/
├── tmp/
├── usr/
└── var/
```

### user's root directory

The user's root directory, that we may refer to as `~`, contains:

```
┌── Desktop/
├── Documents/
├── Downloads/
├── Movies/
├── Music/
├── Pictures/
│
├── Public/
└── Library/
```

###


macOS

Per-instance customization

Global overrides

CSS Module patterns

Style props

Color scheme

Button case study

Default theme

Gray Palette

Dark Palette

Color shades and aliases

Flex

Group

Stack

SimpleGrid

Container

Center

Divider

Space

Paper

Accordion

Appshell

Tabs

Tables introduction

Tables with explicit structure

Tables from data prop

TextInput

NumberInput

FileInput

Date and Time inputs

Native Select

Select

SegmentedControl

Button

Button.Group

ActionIcon

Pagination

Modal

Title

Text

Bar Chart

Progress

RingProgress

Avatar

Notifications

Mantine form

useLocalStorage

useDisclosure

useMantineColorScheme

# Overview

<div class="bookHeroImage" style="padding: 32px;margin: 8px 0;"><svg  xmlns="http://www.w3.org/2000/svg" viewBox="0 0 623 163" style="height:calc(2rem * var(--mantine-scale))" class="m_2075ec07"><g fill="none" fill-rule="evenodd"><path fill="#339af0" fill-rule="nonzero" d="M162.162 81.5c0-45.011-36.301-81.5-81.08-81.5C36.301 0 0 36.489 0 81.5 0 126.51 36.301 163 81.081 163s81.081-36.49 81.081-81.5z"></path><g fill="#fff"><path fill-rule="nonzero" d="M65.983 43.049a6.234 6.234 0 00-.336 6.884 6.14 6.14 0 001.618 1.786c9.444 7.036 14.866 17.794 14.866 29.52 0 11.726-5.422 22.484-14.866 29.52a6.142 6.142 0 00-1.616 1.786 6.211 6.211 0 00-.694 4.693c.197.79.546 1.533 1.028 2.186a6.154 6.154 0 008.634 1.284 50.112 50.112 0 007.947-7.39h17.493c3.406 0 6.174-2.772 6.174-6.194s-2.762-6.194-6.174-6.194h-9.655a49.166 49.166 0 004.071-19.69 49.166 49.166 0 00-4.07-19.692h9.66c3.406 0 6.173-2.771 6.173-6.194 0-3.422-2.762-6.193-6.173-6.193H82.574a50.11 50.11 0 00-7.952-7.397 6.149 6.149 0 00-4.578-1.153 6.189 6.189 0 00-4.055 2.438h-.006z"></path><path d="M56.236 79.391a9.342 9.342 0 01.632-3.608 9.261 9.261 0 011.967-3.077 9.143 9.143 0 012.994-2.063 9.06 9.06 0 017.103 0 9.144 9.144 0 012.995 2.063 9.261 9.261 0 011.967 3.077 9.34 9.34 0 01.63 3.608 9.299 9.299 0 01-2.755 6.395 9.094 9.094 0 01-6.388 2.63 9.094 9.094 0 01-6.39-2.63 9.299 9.299 0 01-2.755-6.395z"></path></g><path fill="currentColor" fill-rule="nonzero" d="M291.736 126.644c1.984 0 3.823-.434 5.518-1.302 1.695-.868 2.542-2.129 2.542-3.782v-77.5c0-2.976-.827-5.063-2.48-6.262-1.653-1.199-3.513-1.798-5.58-1.798-1.901 0-3.555.207-4.96.62-1.405.413-2.666 1.24-3.782 2.48s-2.418 3.059-3.906 5.456l-15.252 27.776-15.128-27.776c-1.323-2.397-2.583-4.216-3.782-5.456-1.199-1.24-2.48-2.067-3.844-2.48-1.364-.413-3.038-.62-5.022-.62-1.984 0-3.823.6-5.518 1.798-1.695 1.199-2.542 3.286-2.542 6.262v77.5c0 1.653.847 2.914 2.542 3.782 1.695.868 3.534 1.302 5.518 1.302 2.067 0 3.927-.434 5.58-1.302 1.653-.868 2.48-2.129 2.48-3.782V67.248l14.26 26.784c.744 1.24 1.591 2.087 2.542 2.542.95.455 1.88.682 2.79.682.992 0 1.984-.248 2.976-.744s1.86-1.323 2.604-2.48l14.384-25.792v53.32c0 1.653.847 2.914 2.542 3.782 1.695.868 3.534 1.302 5.518 1.302zm34.375 1.116c4.298 0 7.956-.992 10.974-2.976 3.017-1.984 5.642-4.257 7.874-6.82v3.596c0 1.405.682 2.604 2.046 3.596 1.364.992 3.08 1.488 5.146 1.488 2.232 0 4.092-.496 5.58-1.488 1.488-.992 2.232-2.19 2.232-3.596V91.18c0-4.216-.889-8.143-2.666-11.78-1.778-3.637-4.609-6.613-8.494-8.928-3.886-2.315-9.052-3.472-15.5-3.472-2.894 0-5.87.372-8.928 1.116-3.059.744-5.642 1.798-7.75 3.162-2.108 1.364-3.162 2.914-3.162 4.65 0 1.819.475 3.596 1.426 5.332.95 1.736 2.294 2.604 4.03 2.604 1.074 0 2.066-.33 2.976-.992.91-.661 2.211-1.302 3.906-1.922 1.694-.62 4.112-.93 7.254-.93 2.81 0 4.98.579 6.51 1.736 1.53 1.157 2.645 2.604 3.348 4.34a14.092 14.092 0 011.054 5.332v1.612h-5.084c-5.704 0-10.726.537-15.066 1.612-4.34 1.075-7.73 2.935-10.168 5.58-2.439 2.645-3.658 6.324-3.658 11.036 0 5.621 1.591 9.775 4.774 12.462 3.182 2.687 6.964 4.03 11.346 4.03zm6.448-11.904c-1.819 0-3.369-.537-4.65-1.612-1.282-1.075-1.922-2.77-1.922-5.084 0-2.315.764-4.03 2.294-5.146 1.53-1.116 3.534-1.84 6.014-2.17 2.48-.33 5.084-.496 7.812-.496h1.86v2.604c0 1.984-.6 3.885-1.798 5.704-1.199 1.819-2.666 3.307-4.402 4.464-1.736 1.157-3.472 1.736-5.208 1.736zm84.169 10.788c2.067 0 3.927-.434 5.58-1.302 1.653-.868 2.48-2.129 2.48-3.782V92.172c0-4.63-.971-8.845-2.914-12.648-1.943-3.803-4.526-6.84-7.75-9.114C410.9 68.137 407.345 67 403.46 67c-4.133 0-7.626.971-10.478 2.914-2.852 1.943-4.898 4.113-6.138 6.51v-3.72c0-1.488-.682-2.687-2.046-3.596-1.364-.91-3.038-1.364-5.022-1.364-2.315 0-4.216.455-5.704 1.364-1.488.91-2.232 2.108-2.232 3.596v48.856c0 1.24.744 2.397 2.232 3.472 1.488 1.075 3.39 1.612 5.704 1.612 2.232 0 4.133-.537 5.704-1.612 1.57-1.075 2.356-2.232 2.356-3.472V92.172c0-2.315.496-4.299 1.488-5.952.992-1.653 2.273-2.935 3.844-3.844 1.57-.91 3.183-1.364 4.836-1.364 1.984 0 3.803.558 5.456 1.674 1.653 1.116 2.955 2.5 3.906 4.154a10.52 10.52 0 011.426 5.332v29.388c0 1.653.868 2.914 2.604 3.782 1.736.868 3.513 1.302 5.332 1.302zm47.432 0c2.315 0 4.03-.703 5.146-2.108 1.116-1.405 1.674-2.976 1.674-4.712 0-1.653-.558-3.183-1.674-4.588-1.116-1.405-2.831-2.108-5.146-2.108h-4.836c-2.563 0-4.36-.496-5.394-1.488-1.033-.992-1.55-2.687-1.55-5.084V79.4h14.632c1.323 0 2.335-.6 3.038-1.798.703-1.199 1.054-2.542 1.054-4.03 0-1.488-.351-2.831-1.054-4.03-.703-1.199-1.715-1.798-3.038-1.798H452.38V46.416c0-1.488-.847-2.687-2.542-3.596-1.695-.91-3.534-1.364-5.518-1.364-1.819 0-3.596.455-5.332 1.364-1.736.91-2.604 2.108-2.604 3.596v60.14c0 6.944 1.963 12.028 5.89 15.252 3.927 3.224 9.61 4.836 17.05 4.836h4.836zM487.232 54.6c2.397 0 4.443-.806 6.138-2.418 1.695-1.612 2.542-3.41 2.542-5.394 0-2.15-.847-3.989-2.542-5.518-1.695-1.53-3.74-2.294-6.138-2.294-2.397 0-4.464.765-6.2 2.294-1.736 1.53-2.604 3.369-2.604 5.518 0 1.984.868 3.782 2.604 5.394 1.736 1.612 3.803 2.418 6.2 2.418zm0 72.044c2.232 0 4.133-.537 5.704-1.612 1.57-1.075 2.356-2.232 2.356-3.472V72.704c0-1.488-.785-2.687-2.356-3.596-1.57-.91-3.472-1.364-5.704-1.364-2.315 0-4.216.455-5.704 1.364-1.488.91-2.232 2.108-2.232 3.596v48.856c0 1.24.744 2.397 2.232 3.472 1.488 1.075 3.39 1.612 5.704 1.612zm65.247 0c2.066 0 3.926-.434 5.58-1.302 1.653-.868 2.48-2.129 2.48-3.782V92.172c0-4.63-.972-8.845-2.914-12.648-1.943-3.803-4.526-6.84-7.75-9.114-3.224-2.273-6.779-3.41-10.664-3.41-4.134 0-7.626.971-10.478 2.914-2.852 1.943-4.898 4.113-6.138 6.51v-3.72c0-1.488-.682-2.687-2.046-3.596-1.364-.91-3.038-1.364-5.022-1.364-2.315 0-4.216.455-5.704 1.364-1.488.91-2.232 2.108-2.232 3.596v48.856c0 1.24.744 2.397 2.232 3.472 1.488 1.075 3.39 1.612 5.704 1.612 2.232 0 4.133-.537 5.704-1.612 1.57-1.075 2.356-2.232 2.356-3.472V92.172c0-2.315.496-4.299 1.488-5.952.992-1.653 2.273-2.935 3.844-3.844 1.57-.91 3.182-1.364 4.836-1.364 1.984 0 3.802.558 5.456 1.674 1.653 1.116 2.955 2.5 3.906 4.154a10.52 10.52 0 011.426 5.332v29.388c0 1.653.868 2.914 2.604 3.782 1.736.868 3.513 1.302 5.332 1.302zm47.68 1.116c4.464 0 8.328-.558 11.594-1.674 3.265-1.116 5.786-2.48 7.564-4.092 1.777-1.612 2.666-3.12 2.666-4.526 0-.827-.248-1.798-.744-2.914a8.641 8.641 0 00-2.108-2.914c-.91-.827-1.984-1.24-3.224-1.24-1.158 0-2.398.372-3.72 1.116-1.323.744-2.894 1.53-4.712 2.356-1.819.827-4.092 1.24-6.82 1.24-4.299 0-7.792-1.095-10.478-3.286-2.687-2.19-4.03-5.063-4.03-8.618v-1.86h25.172c1.901 0 3.74-.186 5.518-.558 1.777-.372 3.244-1.323 4.402-2.852 1.157-1.53 1.736-4.071 1.736-7.626 0-4.63-1.199-8.68-3.596-12.152-2.398-3.472-5.518-6.2-9.362-8.184-3.844-1.984-8.08-2.976-12.71-2.976-5.043 0-9.61 1.137-13.702 3.41-4.092 2.273-7.358 5.29-9.796 9.052-2.439 3.761-3.658 7.874-3.658 12.338v10.54c0 5.043 1.281 9.486 3.844 13.33 2.562 3.844 6.096 6.82 10.602 8.928 4.505 2.108 9.692 3.162 15.562 3.162zm4.092-35.836h-18.104v-3.472c0-1.984.516-3.7 1.55-5.146 1.033-1.447 2.376-2.563 4.03-3.348 1.653-.785 3.43-1.178 5.332-1.178 1.984 0 3.802.413 5.456 1.24 1.653.827 2.976 1.984 3.968 3.472s1.488 3.183 1.488 5.084c0 1.323-.269 2.211-.806 2.666-.538.455-1.509.682-2.914.682z"></path></g></svg></div>

[Mantine](https://mantine.dev/) provides infrastructure for building React apps efficiently, with pre-styled UI components and feature-rich utilities.

### benefits

- solid UI defaults: neutral, minimalist, functional style
- easy-to-use, consistent API (DX)
- rapid development of utilitarian/productivity apps

### mantine style is opinionated and cohesive

Mantine brings a set of cohesive style defaults: if we aim to do a partial style override, we should make it compatible with the Mantine overall look.

Layout components and hooks, on the other hand, can be used in any design.

### mantine's packages

Mantine provides several packages. Mantine's _core_ and _hooks_ are the two main ones. Source code:

- [@mantine/core components (GitHub)](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components)
- [@mantine/hooks hooks (GitHub)](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/hooks/src)

### terminology: components and component variants

Mantine provides components, and for some of them, _variants_. For example,
it provides the _Button_ component, and for it, it provides the _outline_ and _filled_ variants.

### terminology: inner-elements

Components are constructed through inner-elements, each with a name, the first being the _root_ element.

For example, _Slider_ is built on top of _root_ (which happens to be a `<div>`), and various other inner-elements such as _mark_, _track_ and _bar_. The point of having named inner-elements is for styling: we target inner-elements with their name.

In this document, and because the _root_ element is special, we sometimes exclude it from the inner-elements category to treat it differently.

The component is _polymorphic_ when we can change which HTML element is used as the component's _root_ element (we set it in the _component_ prop). For example, we can ask to use an anchor tag `<a>` for the root of a `Button` instead of `<button>` , when the action is really navigation.

### customization routes

There are three main ways to customize style:

- Per-instance customization: the scope of the change is local to a single instance of a component.
- Component global override: override a Mantine component globally, affecting all instances.
- Global override of style primitives: override a style primitive, affecting all components (and instances) that depend on it.

### shipped stylesheets

The stylesheets [shipped on npm](https://www.npmjs.com/package/@mantine/core?activeTab=code) have been processed by PostCSS.

Mantine ships two kind of stylesheets:

- it ships a standalone 232kb stylesheet that includes style for all core elements.
- it also ships smaller stylesheets, focusing on one or more components.



# Per-instance customization



### per-instance customization (inline customization)

We want to customize a single instance of a component. We do so by settings props, classes or adding inline CSS:

```tsx
<Button /* customize this very button */></Button>
```

### props that work on all Mantine components

Mantine's _style props_ are props that work on all Mantine components, and which set a single style aspect:

```tsx
<Box m={4}></Box>
```

Note: The style targets the _root_ element, with no granularity for other inner-elements.

### props specific to one or more components

Some props are unique to one or more components. They either determine the style or add to the component's inner structure by toggling inner-elements. For example, _TextInput_ accepts the _label_ prop to add a `<label>` element to its inner-structure:

```tsx
<TextInput label="Username"></TextInput>
// adds:
<label>Username</label>
```

### target inner-elements with _styles_ and _classNames_

We target inner-elements by specifying their name. For each inner-element, we pass either a style object or a set of classes, depending on the pattern picked:

```tsx
 <Button
	styles={{ // styles pattern
        root: { backgroundColor: 'red', height: 16},
        label: { color: 'blue' },
      }}
```

```tsx
<Button
    classNames={{
        // classNames pattern
        root: "pinkbutton-root",
        label: "pinkbutton-label",
    }}
/>
```

### (fallback) undiscriminated styling with the _style_ or _className_ React props

When providing style with _style_ or _className_, there is no granularity as to which inner-element we target: the style we provide applies to the component's _root_ element, similar to style props.

### class naming patterns (when not using CSS modules)

Since we target inner-elements:

- we add the inner-element's name to the class name,
- we namespace the class with the kind of variant we want to create, such as`.pinkbutton-`:

```css
.pinkbutton-root {
}
.pinkbutton-label {
}
```

Note: a cleaner approach is to a create a separate CSS module (`PinkButton.module.css`), having classes named purely based on inner-elements (such as `.label`), without a namespace (see _CSS module patterns_).

# Global overrides



Global overrides, also called theming, can be done by:

- overriding a component, affecting all instances across the app:
    - We implement component-scoped pre-defined classes, such as `mantine-Button-root`.

- overriding style-primitives, affecting all components that depend on it:
    - We edit theme properties in `createTheme({})`
    - or we edit Mantine's CSS variables directly

### set theme properties

We create a custom theme. For example, we control font weights across the app with `fontWeights`. Under the hood, it sets the `--mantine-font-weight-xxx` CSS variables:

```ts
const theme = createTheme({
    fontWeights: {
        medium: "500",
    },
})
```

### set CSS variables directly

```css
:root {
    --mantine-font-weight-medium: 500;
}
```

### implement component-scoped empty classes

Mantine adds empty classes to its components' inner-elements (including _root_). By implementing them, we override those inner-elements globally.

For example, Mantine adds `mantine-Button-root` to the Button's _root_ element. We implement the class if needed:

```css
.mantine-Button-root {
    border-width: 2px;
}
```

### component-scoped empty classes specificity

Empty classes have the same specificity than Mantine's internal classes. As such, we implement overrides in a stylesheet than we import after Mantine's one.

# CSS Module patterns



### CSS module overview

A CSS module is a regular stylesheet (CSS file) whose classes are subject to processing.

A processor parses classes in the stylesheet (such as `superGreat`) and derive unique names (such as `superGreat_1kmox6oL39`). It then produces a derived stylesheet using the unique class names:

```css
.superGreat_1kmox6oL39 {
} /* post-processing */
```

### the class map object

Since the developer only knows about the pre-processed class names (such as `superGreat`), the processor creates a JS object mapping the class names to their post-processed name (a _class map_ object). The developer only interacts with this map. We often call it `classes`:

```tsx
<div className={classes.superGreat}></div> // class="superGreat_1kmox6oL3"
```

When using a bundler that supports CSS modules, we import the map directly from the CSS module path:

```tsx
import classes from "xxx.module.css"
```

Note: We avoid hyphens in class names, because it forces the use of raw strings in property lookups:

```tsx
<div className={classes["super-great"]}></div> // superGreat_1kmox6oL3
```

## Mantine patterns with CSS modules

### targeting inner elements directly

In one CSS module, we target the inner-elements of a single Mantine component (virtually creating a variant of this component).

### module name

As the module defines style for a custom variant, we name the module accordingly, e.g.: `PrimaryButton.module.css`.

### name classes according to inner elements

We name classes according to the inner-element they target, such as _root_ or _label_:

```css
/* PrimaryButton.module.css */
.root {
}

.root:hover {
}

.label {
}
```

We then attach classes to the inner slots of _classNames_:

```tsx
<Button
classNames={{
        root: classes.root,
        label: classes.label,
    }}
  >
```

Since the class map fields already take the name of the inner-elements, they cleanly match the API expected by `classNames`: as such, we provide the class map itself to _classNames_:

```tsx
{/* cleaner */}
<Button classNames={classes}>
```

# Style props



### style props work on all Mantine components

Mantine's _style props_ are props that work on all Mantine components. They set a single style aspect, and affect the _root_ element, with no granularity for inner-elements:

```tsx
<Box m={4}></Box>
```

### immediate value or alias

When using a prop, we provide either:

- an immediate value, such as `4px`,
- or, for some props, an alias, such as `xl`, `sm` or `indigo`. The [theme](https://github.com/mantinedev/mantine/blob/master/packages/%40mantine/core/src/core/MantineProvider/default-theme.ts) defines the resolved values. For example, the spacing aliases resolve to the following values by default:

```ts
// alias default values in theme:
 spacing: {
    xs: rem(10),
    sm: rem(12),
    md: rem(16), // i.e. 16px
    lg: rem(20),
    xl: rem(32),
  },
```

Note: using an alias instead of an immediate value can make code less straightforward because the resolved value is not immediately clear.

### responsiveness: provide alternative values

We can provide alternative values instead of a single one. This fits responsive designs, where mobile and desktop have different values:

```tsx
<Flex
 direction=	{{ base: 'column',sm: 'row' }}
 gap=		{{ base: 'sm', 	sm: 'lg' }}
 justify=	{{ base: 'sm', 	sm: 'lg' }}
>
```

- _base_ provides the default, mobile-centric value. Its exact scope depends on other breakpoints, but it always devices with screen under 576p width. For reference, all iPhones are under 450p width.
    - The _xs_ breakpoint activates at 576p. It targets phablets and bigger devices.
    - The _sm_ breakpoints activates at 768p (48em). It targets tablets and wider screens. For reference, iPads start at 768px.

## list of style props

The _resolved alias_ information only matters when we use aliases, such as `sm` or `indigo`.

### margin

| Prop   | CSS Property            | resolved alias |
| :----- | ----------------------- | -------------- |
| **m**  | margin                  | theme.spacing  |
| **mt** | marginTop               | -              |
| **mb** | marginBottom            | -              |
| **ml** | marginLeft              | -              |
| **mr** | marginRight             | -              |
| **mx** | marginRight, marginLeft | -              |
| **my** | marginTop, marginBottom | -              |

### padding

| Prop   | CSS Property              | resolved alias |
| :----- | ------------------------- | -------------- |
| **p**  | padding                   | theme.spacing  |
| **pt** | paddingTop                | -              |
| **pb** | paddingBottom             | -              |
| **pl** | paddingLeft               | -              |
| **pr** | paddingRight              | -              |
| **px** | paddingRight, paddingLeft | -              |
| **py** | paddingTop, paddingBottom | -              |

### typography

| Prop    | CSS Property   | resolved alias    |
| :------ | -------------- | ----------------- |
| **ff**  | fontFamily     |                   |
| **fz**  | fontSize       | theme.fontSizes   |
| **fw**  | fontWeight     |                   |
| **lts** | letterSpacing  |                   |
| **ta**  | textAlign      |                   |
| **lh**  | lineHeight     | theme.lineHeights |
| **fs**  | fontStyle      |                   |
| **tt**  | textTransform  |                   |
| **td**  | textDecoration | –                 |

### size

| Prop    | CSS Property | resolved alias |
| :------ | ------------ | -------------- |
| **w**   | width        | theme.spacing  |
| **miw** | minWidth     | -              |
| **maw** | maxWidth     | -              |
| **h**   | height       | -              |
| **mih** | minHeight    | -              |
| **mah** | maxHeight    | -              |

### position

| Prop       | CSS Property |
| :--------- | ------------ |
| **pos**    | position     |
| **top**    | top          |
| **left**   | left         |
| **bottom** | bottom       |
| **right**  | right        |
| **inset**  | inset        |

### other props

| Prop        | CSS Property         | resolved alias           |
| :---------- | -------------------- | ------------------------ |
| **display** | display              |                          |
| **flex**    | flex                 |                          |
| **bd**      | border               |                          |
| **bdrs**    | borderRadius         |                          |
| **bg**      | background           | theme.colors             |
| **bgsz**    | backgroundSize       |                          |
| **bgp**     | backgroundPosition   |                          |
| **bgr**     | backgroundRepeat     |                          |
| **bga**     | backgroundAttachment |                          |
| **c**       | color                | theme.colors gray.5 blue |
| **opacity** | opacity              |                          |

# Color scheme



Mantine defaults to a `light` color scheme regardless of the device's active color scheme.

We can change the default to `dark` or `auto` instead. `auto` conforms to the user's device color scheme:

```tsx
<MantineProvider defaultColorScheme="auto"></MantineProvider>
```

# Button case study



### Button implementation

The [Button source code](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components/Button) includes the TypeScript file (`Button.tsx`) and the CSS stylesheet (`Button.module.css`).

### HTML default structure (simplified)

- the _root_ is a `<button>`.
- _inner_, _section_, _label_ and _loader_ are `<span>` elements:
    - _loader_ contains a loader, if any
    - _inner_ contains the _label_ and _sections_
        - the _label_ contains the button's text.
        - a _section_ is a container for an icon, if applicable:

```tsx
<button {/* root */}>
    <span {/* 1.0 loader */} />
    <span  {/* 2.0 inner */}>
        <span {/* 2.1 section (icons..)  */}/>
        <span {/* 2.2 label (button text)  */}/>
      </span>
    </span>
</button>
```

Mantine adds its internal classes (e.g. _m-77c9d27d_) along with unimplemented empty classes (e.g. _mantine-Button-root_) to the inner-elements:

```tsx
<button class="m-77c9d27d mantine-Button-root">
    <span class="m-80f1301b mantine-Button-inner">
        <span class="m-811560b9 mantine-Button-label">Save</span>
    </span>
</button>
```

### the stylesheet: a CSS module

The Button's [CSS module stylesheet](https://github.com/mantinedev/mantine/blob/master/packages/%40mantine/core/src/components/Button/Button.module.css) targets inner-elements with classes of the same name:

```css
.loader {
    position: absolute;
    left: 50%;
    top: 50%;
}
```

The [.tsx file](https://github.com/mantinedev/mantine/blob/master/packages/%40mantine/core/src/components/Button/Button.tsx) imports the _classes_ object and plugs it to _Button.classes_.

### (advanced) component-agnostic internal classes and data attributes

Mantine also adds component-agnostic internal classes, such as _mantine-active_ and _mantine-focus-auto_. They are placed preemptively, and their style triggers on specific states. For example, `mantine-active` activates its style on the active state:

```css
mantine-active:active {
    transform: translateY(calc(0.0625rem));
}
```

Mantine can also add internal data-attributes such as `data-centered="true"` to set a specific style:

```css
.m_a3c6e060[data-centered] {
    display: flex;
    justify-content: center;
    align-items: center;
}
```

# Default theme



The default [theme](https://github.com/mantinedev/mantine/blob/master/packages/%40mantine/core/src/core/MantineProvider/default-theme.ts) covers multiple design areas and categories.

It defines some style primitives directly. It also defines some _aliases_ (such as `sm`), and what value they resolve to.

See also docs for [v7](https://v7.mantine.dev/theming/default-theme/) and [v9](https://mantine.dev/theming/theme-object/).

### spacing values

Spacing determines space _between_ elements and space _inside_ elements. It is used for:

- gap, for _Group_, _Flex_, and _Stack_.
- padding.
- margin, such as for _Divider_
- width and height props such as `w` and `h`, such as for _Space_.

```tsx
xs: 10px
sm: 12px
md: 16px
lg: 20px
xl: 32p
```

### radius values

The border radius is used for _Paper_, _Dialog_ and _Modal_, _Button_ and _Tooltip_.

```tsx
"defaultRadius": "md" // changed in v9 from "sm" to "md"
```

```tsx
xs: 2px
sm: 4px // former default
md: 8px // (d)
lg: 16px
xl: 32px
```

### breakpoints

A set of thresholds, to activate style conditionally:

```tsx
  "breakpoints": {
    "xs": "36em", // 576px
    "sm": "48em", // 768px
    "md": "62em",
    "lg": "75em",
    "xl": "88em"
  },
```

The `sm` breakpoint targets tablets and wider devices.

We use those thresholds in styles props to provide alternative values.

### font sizes

Those font sizes can be used in the `fz` style prop:

```ts
"fontSizes": {
    "xs": 12px
    "sm": 14px
    "md": 16px,
    "lg": 18px
    "xl": 20px
  },
```

_headings_ have a different set of values.

### weights

Note: _medium_ was changed from _500_ to _600_ in Mantine v9.

```ts
"fontWeights": {
    "regular": '400',
    "medium": '600',
    "bold": '700',
  }
```

### line heights

The aliases can be used in the `lh` style prop:

```ts
  "lineHeights": {
    xs: 1.4,
    sm: 1.45,
    md: 1.55, // (d)
    lg: 1.6,
    xl: 1.65
  },
```

The default line height is 1.55:

```css
--mantine-line-height: 1.55;
```

### headings

```tsx
headings: {
    fontFamily: DEFAULT_FONT_FAMILY,
    fontWeight: '700',
    textWrap: 'wrap',
    sizes: {
      h1: { fontSize: rem(34), lineHeight: '1.3' }, // 34px
      h2: { fontSize: rem(26), lineHeight: '1.35' },
      h3: { fontSize: rem(22), lineHeight: '1.4' },
      h4: { fontSize: rem(18), lineHeight: '1.45' },
      h5: { fontSize: rem(16), lineHeight: '1.5' },
      h6: { fontSize: rem(14), lineHeight: '1.5' },
    },
  },
```

# Gray Palette



### overview

Mantine's `gray` palette is specifically designed for light mode:

- It offers a large number of whites and light grays (6) for backgrounds. It starts at `#F8F9FA`, not pure white.
- It offers very few dark grays (3-4) for text. It doesn't include pure black.

It has a blue tint (slate gray).

### values

| **Token** | **Description**      | **Hex Value** |
| --------- | -------------------- | ------------- |
| `gray.0`  | white                | `#F8F9FA`     |
| `gray.1`  | white                | `#F1F3F5`     |
| `gray.2`  | white gray           | `#E9ECEF`     |
| `gray.6`  | dim gray (secondary) | `#868e96`     |
| `gray.7`  | dim gray (secondary) | `#495057`     |
| `gray.8`  | very dark gray       | `#343A40`     |
| `gray.9`  | very dark gray       | `#212529`     |

### use in backgrounds

- Backgrounds can be pure white, such as the site's global background or controls' background.

- Controls' background can go darker on hover. This is the case for buttons, and Select's options: `gray.1`

### use in text

The text is black-ish or gray-ish depending on its importance and role:

- gray 9 (readable black for body text)
- gray 8 (readable black)
- dark 7 (dimmed)
- gray 6 (gray) for secondary text, and input description
- pure black text (optional)
    - some headings
    - body text
    - input label
    - button label

# Dark Palette



### overview

Mantine's `dark` palette is designed for dark mode, and is used by the Mantine dark theme. It offers several darks and grays for backgrounds (6), and few whitish (2-3) for text.

It is a neutral gray palette, but used to be a slate gray palette (blue tint) before Mantine 7.3.

| **Token** | **Look** | **Alias**       | **Value** | **Value** | White **%** |
| --------- | -------- | --------------- | --------- | --------- | ----------: |
| `dark.0`  | whitish  | _text_          | `#c9c9c9` | `#c9`     |         79% |
| `dark.1`  | whitish  |                 | `#b8b8b8` | `#b8`     |         72% |
| `dark.2`  | dimmed   | _dimmed_        | `#828282` | `#82`     |         51% |
| `dark.3`  | dimmed   | _placeholder_   | `#696969` | `#69`     |         41% |
| `dark.4`  |          |                 | `#424242` | `#42`     |         26% |
| `dark.5`  | dark     | _default-hover_ | `#3b3b3b` | `#3b`     |         23% |
| `dark.6`  | dark     | _default_       | `#2e2e2e` | `#2e`     |         18% |
| `dark.7`  | dark     | _body_          | `#242424` | `#24`     |         14% |
| `dark.8`  | black    |                 | `#1f1f1f` | `#1f`     |         12% |
| `dark.9`  | black    |                 | `#141414` | `#14`     |          8% |

### use in backgrounds

- The page's global background defaults to dark 7. We may go darker with dark 8.
- Controls have a lighter background: dark 6, and even lighter on hover: dark 5.
  Sometimes, hover goes to a darker background instead: such as for hovered options in a Select control: dark 8.

### use in text

- The text uses light colors:
    - pure white (bright white for some headings)
    - dark 0 (readable white for body text)
    - dark 1 (slightly dimmed)
    - dark 2 (dimmed, secondary text, matches `c=dimmed`)
- The Button label is pure white, both for _filled_ and _default_ variants.
- The inputs' labels are dark 0, the optional descriptions are dark 2, aka dimmed.
- `dimmed` text is dark 2. It's used for secondary text and labels.

### v6 values (slate)

The v6 palette had a blue tint:

| **Token** | **v6 value** |
| --------- | ------------ |
| `dark.0`  | `#C1C2C5`    |
| `dark.1`  | `#A6A7AB`    |
| `dark.2`  | `#909296`    |
| `dark.3`  | `#5c5f66`    |
| `dark.4`  | `#373A40`    |
| `dark.5`  | `#2C2E33`    |
| `dark.6`  | `#25262b`    |
| `dark.7`  | `#1A1B1E`    |
| `dark.8`  | `#141517`    |
| `dark.9`  | `#101113`    |

### revert to blue-tint dark palette

```tsx
const theme = createTheme({
    colors: {
        dark: [
            "#C1C2C5",
            "#A6A7AB",
            "#909296",
            "#5c5f66",
            "#373A40",
            "#2C2E33",
            "#25262b",
            "#1A1B1E",
            "#141517",
            "#101113",
        ],
    },
})
```

# Color shades and aliases



### overview

Mantine uses CSS variables to define color shades. CSS variables start with the `--mantine-color` prefix.

- Mantine defines 14 colors.
- Mantine defines 10 shades for each color, 0 to 9, following the pattern of `--mantine-color-dark-0`.
- It defines _aliases_, or _semantic_ CSS variables, such as `--mantine-color-text`, which resolve to a given shade, such as `--mantine-color-dark-0`.
    - The resolved value depends on the active color scheme: `dark` or `light` (see below).

Some _aliases_ are linked to a specific variant. For example, `--mantine-color-default` is linked to the _default_ variant, and defines its background color.

## dark color-scheme values

The aliases resolve to the following values:

| semantic suffixes      | value                  | note       |
| ---------------------- | ---------------------- | ---------- |
| --mantine-color-bright | --mantine-color-white  | text       |
| -text                  | --mantine-color-dark-0 | text       |
| -dimmed                | --mantine-color-dark-2 | text       |
| -placeholder           | --mantine-color-dark-3 | text       |
| -body                  | --mantine-color-dark-7 | background |
| -anchor                | --mantine-color-blue-4 | link       |
| -error                 | --mantine-color-red-8  | form error |
| -red-text              | --mantine-color-red-4  | ?          |
| -scheme                | "dark"                 |            |

### variant: _"default"_ aliases

note: it comes with a border.

While the default for hover is _dark-5_, we can also use _dark-4_ or _dark-6_.

| semantic suffixes | value                  | note       |
| ----------------- | ---------------------- | ---------- |
| default-color     | --mantine-color-white  | text       |
| default           | --mantine-color-dark-6 | background |
| default-hover     | --mantine-color-dark-5 | background |
| default-border    | --mantine-color-dark-4 | border     |

### color: _"dark"_ aliases

it comes with values for several variants. It has no border.

| semantic suffixes  | value                  |
| ------------------ | ---------------------- |
| dark-text          | --mantine-color-dark-4 |
| dark-filled        | --mantine-color-dark-8 |
| dark-filled-hover  | --mantine-color-dark-7 |
| dark-light         | rgba(36, 36, 36, 0.15) |
| dark-light-hover   | rgba(36, 36, 36, 0.2)  |
| dark-light-color   | --mantine-color-dark-3 |
| dark-outline       | --mantine-color-dark-4 |
| dark-outline-hover | rgba(36, 36, 36, 0.05) |

### color: _"gray"_ aliases

it comes with values for several variants.

| suffix             | value                     |
| ------------------ | ------------------------- |
| gray-text          | --mantine-color-gray-4    |
| gray-filled        | --mantine-color-gray-8    |
| gray-filled-hover  | --mantine-color-gray-9    |
| gray-light         | rgba(134, 142, 150, 0.15) |
| gray-light-hover   | rgba(134, 142, 150, 0.2)  |
| gray-light-color   | --mantine-color-gray-3    |
| gray-outline       | --mantine-color-gray-4    |
| gray-outline-hover | rgba(206, 212, 218, 0.05) |

## light color-scheme values

# Flex



A bare-bones flex container, with nothing set besides _display: flex_.

### override CSS defaults

We can override CSS defaults:

- Switch the `direction` to vertical (_column_). It is horizontal (_row_) by default
- Increase the `gap` (defaults to 0)
- Control `justify`, aka main axis alignment, which default to _flex-start_.
- Control `align`, aka cross-axis alignment, which defaults to _stretch_.

Example of a responsive flex container, that is vertical in mobile:

```tsx
<Flex
    direction={{ base: "column", sm: "row" }}
    gap={{ base: "sm", sm: "lg" }}
    justify={{ base: "flex-start", sm: "space-between" }}
/>
```

# Group



A layout component that layouts elements horizontally and adds space between them.

The container spans the whole line. It uses a horizontal flex under the hood.

Differences with a stock horizontal flex:

- It adds `gap` between elements (defaults to _md_, aka 16px).
- It centers elements vertically, with `align`, instead of stretching them.
- It wraps to the next line if needed (aka multi-line flex). We can revert to mono-line with (`wrap="nowrap"`), which sets the underlying _flex-wrap_.

### the _grow_ variant (override)

- The `grow` variant aims to fill the container horizontally by growing children:
    - It sets _flex-grow: 1_ on children.
    - By default, it makes them same-width (by capping them to the same _max-width_, set to a share of the line, which in turns make them fit in one line).
        - (advanced) If we turn off capping (set `preventGrowOverflow` to false): elements can go to the next line if there is not enough room for all of them in the non-grown version. (do not use)
        - (advanced) If we add `nowrap`, it's back a mono-line flex where children grow proportionally with their _flex-basis_ (It's convoluted), cutting any overflow if the single line is not wide enough.

### other overrides

- Align items horizontally with `justify`. It defaults to _flex-start_ (like default flexes).

# Stack



Layout elements vertically and add space between them.

The container spans the whole line (because its _width_ is _auto_). It uses a vertical flex under the hood. Items default to spread horizontally within the container.

Differences with a stock flex:

- It is vertical
- It sets a `gap` (16px by default)

Other settings and their default:

- `justify`: elements sit at the top by default (_flex-start_)
- `align`: elements fill the stack horizontally by default (_stretch_)

# SimpleGrid



Set up a column-based layout with a given number of equal-width columns:

```ts
<SimpleGrid cols={3}>{/* items */}</SimpleGrid>
```

The grid container spans the whole line and the columns together span the whole line too.

The grid container adds space between tracks by default (_16px_), both horizontally and vertically, through `spacing` and `verticalSpacing`.

We set the number of columns with `cols`. It defaults to a single track. The best practice is to adapt the number of columns based on screen size:

```tsx
<SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }}>{/* items */}</SimpleGrid>
```

# Container



A wrapper that centers the content and keeps it aways from screen edges.

It can wrap the main column of a website, adding padding on mobile and centering on desktop.

### grid version

The grid version uses a grid layout and centers stuff with grid positioning.

### max-width version

The default version comes with a max-width (for desktop) and some padding (for mobile):

- It centers the content with _margin: auto_.
- The max-width defaults to _md_ (aka 960px). We change it with `size`. For example, we can pick 720px (_sm_) instead.
- To remove indirection, we can also set max-width with `maw`.
- The default padding is 16px, aka _md_. We change it with the `px` style prop.

### fluid version

We may opt for a fluid container, which expands horizontally, with the `fluid` prop. It only comes with some padding, at 16px.

Note: a _Box_ with horizontal padding has the same effect than _fluid_.

# Center



Center the child or the group of children horizontally and vertically.

Under the hood, it uses a flex container with _justify_ and _align_ to center the inner content.

### vertical-centering and height

Vertical centering will only have an effect if _Center_'s height is bigger than the inner-content.

### width.

The container spreads horizontally (width: auto). It compacts its children to `max-content`, then centers them horizontally.

We can prevent compaction by setting the group of children to _width: 100%_. In this case, we lose horizontal centering.

# Divider



Separate items or sections with a visible line, similar in essence to the \<hr\> element.

Under the hood, it is an empty element whose border acts as the visible line.

- The line is horizontal by default, we can set it to vertical with `orientation`.
- We set the line thickness with `size`. It defaults to 1px.
- The line is solid by default. We switch to _dashed_ or _dotted_ with `variant`.
- The line doesn't add margin around itself by default. We can add margin with _my_ or _mx_.
- The line's color defaults to:
    - `--mantine-color-dark-4: #424242;` in dark mode (dark gray)
    - `--mantine-color-gray-3: #dee2e6;` in light mode (light gray)

# Space



Separate items with some white space. Mantine uses an empty element with some explicit size. It defaults to zero size. We set the height or the width:

- Set vertical spacing with `h`, usually in a stack-like layout.
- Set horizontal spacing with `w`, usually in a horizontal flex-like layout.

# Paper



Encapsulate some UI to set it apart visually.

The Paper's default background is the same as the _body_'s default background, aka `--mantine-color-body`.

- In light mode, it is white \#FFF.
- In dark mode, it is _dark.7_.

As such, we may have to override's Paper background with `bg`.

Paper also adds a `radius` (_theme.defaultRadius_) which defaults to _8px_.

### customizations

- Add a pre-styled border with `withBorder` (boolean)
- Add a pre-styled shadow with `shadow`. We specify an alias (e.g. `sm`), or a CSS _box-shadow_ literal.

# Accordion



An accordion offers one or more items that can expand to disclose more content when interacted with.

### item preview and panel disclosure

Accordion items start as clickable previews (_Accordion.Control_) and embed
a panel, toggled on click.

Mantine mounts all panels immediately, regardless of their toggled state.

### variants

By default, items are separated by a thin line (_default_). We can use other [variants](https://mantine.dev/core/accordion/), such as _separated_.

### behavior

By default, a single panel is displayed at a time. Clicking on another item closes the currently opened one. We can allow multiple concurrent panels with the `multiple` prop.

### (misc) use a panel as a form

The panel may be a form. In that case, we can set the chevron as a plus sign, to signal we add some data.

We set the chevron style at the Accordion root element's level, since all items use it.

```tsx
<Accordion variant="separated" chevron={<IconPlus />}>
    <Accordion.Item value="item1">
        <Accordion.Control>Log Workout</Accordion.Control>
        <Accordion.Panel>Content</Accordion.Panel>
    </Accordion.Item>
</Accordion>
```

# Appshell



Appshell is a mega layout component that manages:

- The _header_ on-top of the page, also called the banner.
- The _main_ section, below the header
- The left-side _navbar_ and the right-side _aside_ (if applicable)

### synopsis

```tsx
<AppShell header={{}} navbar={{}} aside={{}} footer={{}}>
    <AppShell.Header />
    <AppShell.Navbar />
    <AppShell.Aside />
    <AppShell.Main />
    <AppShell.Footer />
</AppShell>
```

Note: the configuration objects are set on `AppShell` as props. They are required when we use the corresponding component (except for `AppShell.Main`).

### header

The header usually manages:

- the burger button
- the logo
- (optional) the dark mode toggle, the user button, a set of links.

```tsx
<AppShell.Header>
    <Burger opened={opened} onClick={toggle} hiddenFrom="sm" />
</AppShell.Header>
```

### configure the header

We commonly set the _height_:

```tsx
<AppShell header={{ height: 60 }} /* ... */ />
```

### navbar

```tsx
<AppShell navbar={{}} /* ... */ />
```

The _navbar_ stands on the left side. On mobile, it only appears in a transient fashion, and is collapsed by default. On desktop it is commonly always-on, though we sometimes offer to collapse it too.

We control the collapsing state with _collapsed_, and the breakpoint from mobile to desktop with _breakpoint_:

- `collapsed` receives up to two boolean state variables: one for _mobile_ and one for _desktop_. Most of the time, we only use the _mobile_ state variable, and keep desktop always opened.
- `breakpoint` controls when the collapse logic switches from mobile to desktop, aka when to use the mobile opened state versus the desktop opened state.
- The burger button is responsible for toggling the state on and off:

```tsx
const [mobileOpened, { toggle: toggleMobile }] = useDisclosure()

return (
    <AppShell
        navbar={{
            collapsed: { mobile: !opened },
            breakpoint: "sm",
        }}
    >
        <AppShell.Header>
            <Burger opened={opened} onClick={toggle} hiddenFrom="sm" />
        </AppShell.Header>
    </AppShell>
)
```

We hide the mobile burger on desktop with `hiddenFrom` since it only controls the mobile state.

### supporting collapse on desktop

If we support desktop collapse, we provide a separate burger button controlling the desktop state.

We use an additional boolean state variable, and provide it to `collapsed`.

Note: the desktop burger button commonly keeps the same appearance instead of showing a close icon, since we are not really closing anything, contrary to mobile.

We display it only on desktop with _visibleFrom_:

```tsx
const [mobileOpened, { toggle: toggleMobile }] = useDisclosure(false)
const [desktopOpened, { toggle: toggleDesktop }] = useDisclosure(true)

return (
    <AppShell
        navbar={{
            collapsed: { mobile: !mobileOpened, desktop: !desktopOpened },
            breakpoint: "sm",
        }}
    >
        <AppShell.Header>
            {/* mobile */}
            <Burger opened={mobileOpened} onClick={toggleMobile} hiddenFrom="sm" />
            {/* desktop */}
            <Burger opened={false} onClick={toggleDesktop} visibleFrom="sm" />
        </AppShell.Header>
    </AppShell>
)
```

### navbar: desktop width

In mobile, the opened navbar is always full screen.

On desktop, we control the width with `width`. We provide an immediate value or an object with two or more values:

```tsx
navbar={{ width: 300, /* ... */ }}
```

### navbar: top and bottom sections

We can split the navbar into _AppShell.Sections_. One of them can grow.

```tsx
<AppShell.Navbar>
    <AppShell.Section grow> </AppShell.Section>
    <AppShell.Section> </AppShell.Section>
</AppShell.Navbar>
```

### Appshell.Main

The container for the main panel.

Its background defaults to the body's background color (_--mantine-color-body_):

- In light mode, It is _white_. We can pick a light gray background such as _gray.1_, so that inner containers may stand out as _white_.
- In dark mode, it is _dark.7_. We can pick _dark.8_ so that inner elements may standout as _dark.7_.

```tsx
const backgroundColor = colorScheme === "dark" ? "dark.8" : "gray.1"
```

# Tabs



The tabs widget is primarily a navigation control, where we switch between sections.

We show a tab bar with `Tabs.List`:

```tsx
<Tabs> {/* container */}
	<Tabs.List> {/* header, horizontal or vertical */}
		<Tabs.Tab>	{/* tab */}
    <Tabs.Tab>	{/* tab */}
    <Tabs.Tab>	{/* tab */}
  </Tabs.Tab>
	<Tabs.Panel> {/* tab panel */}
  <Tabs.Panel> {/* tab panel */}
  <Tabs.Panel> {/* tab panel */}

```

### uncontrolled mode

- We select the initial tab with `defaultValue`.
- Pairs of matching `Tabs.Tab` and `Tabs.Panel` share the same `value`.
- (optional) We make the list mobile-friendly with `Scroller`: we wrap the `.Tab` components with it.

```tsx
<Tabs defaultValue="first" color="dimmed">
    <Tabs.List>
        <Scroller>
            <Tabs.Tab value="first">Proteins</Tabs.Tab>
            <Tabs.Tab value="second">Workouts</Tabs.Tab>
        </Scroller>
    </Tabs.List>
    <Tabs.Panel value="first">{/* Proteins */}</Tabs.Panel>
    <Tabs.Panel value="second">{/* Workouts */}</Tabs.Panel>
</Tabs>
```

### controlled mode

Note: In controlled mode, the selected tab derives from state. The state is subscribed to through `value`, while `onChange` handles tentative tab changes:

```tsx
const [authMode, setAuthMode] = useState("login")

;<Tabs value={authMode} onChange={(v) => setAuthMode(v!)}>
    <Tabs.Tab value="login">Login</Tabs.Tab>
    <Tabs.Tab value="signup">Sign up</Tabs.Tab>
</Tabs>
```

### Tabs.Panel are optional in control mode

A _Tabs.Panel_ wraps its content as a div and doesn't bring style by default

When its _value_ is not matched, it uses `display:none` to hide its content.

We technically don't need a _Tabs.Panel_: we can do the conditional display manually based on state, or use an always-on component whose data derives from the selected tab name (do not use).

### panels default to lazy-mounted, and sticking around when unselected

A given panel mounts the first time it is selected.

- By default, it doesn't unmount when unselected. It uses the React `<Activity>` _hidden_ feature to hide itself:
    - Its state is preserved.
    - The Effects are destroyed, aka the effect cleanup functions run just the same as if the component had unmounted, and the effects run again when the tab is selected back. (the default is `keepMountedMode="activity"`)

- We can ask a "real" unmount with `keepMounted={false}` which adds the `display=none` HMTL attribute.
- The `keepMountedMode="display-none"` option is special because, when combined with the default `keepMounted={true}`, all tabs mount immediately (not lazily), and their effect all run at the same time. Since they stay mounted, the cleanup effect doesn't run when switching tabs and the one-time effect doesn't run when switching to a tab. They appear hidden only through CSS.

# Tables introduction



### abstract

A table works with an array of items, where each item is a row, and each item's property (or member) is a cell.

An item may come as an object or as an array. Mantine supports both:

### the item as an object

```ts
const items = [
    { position: 6, mass: 12.011, symbol: "C", name: "Carbon" },
    { position: 7, mass: 14.007, symbol: "N", name: "Nitrogen" },
    { position: 39, mass: 88.906, symbol: "Y", name: "Yttrium" },
    { position: 56, mass: 137.33, symbol: "Ba", name: "Barium" },
    { position: 58, mass: 140.12, symbol: "Ce", name: "Cerium" },
]
```

### the item as an array

```ts
const items = [
    [6, 12.011, "C", "Carbon"],
    [7, 14.007, "N", "Nitrogen"],
    [39, 88.906, "Y", "Yttrium"],
    [56, 137.33, "Ba", "Barium"],
    [58, 140.12, "Ce", "Cerium"],
]
```

Note: we can transform an array of objects to an array of arrays by mapping over it:

```ts
players.map((p) => [p.name, p.level, p.class])
```

### headers

A table usually comes with a headers row. We store them in an array:

```ts
const headers = ["Element position", "Atomic mass", "Symbol", "Element name"]
```

# Tables with explicit structure



### overview

- The header uses _Thead_ and _Th_
- The body uses _Tbody_ and _Td_:

```tsx
<Table>
    {/* 1. header */}
    <Table.Thead>
        <Table.Tr>
            <Table.Th>{col1Label}</Table.Th>
            <Table.Th>{col2Label}</Table.Th>
            <Table.Th>{col3Label}</Table.Th>
        </Table.Tr>
    </Table.Thead>

    {/* 2. rows */}
    <Table.Tbody>
        <Table.Tr>
            <Table.Td>{item1.name}</Table.Td>
            <Table.Td>{item1.level}</Table.Td>
            <Table.Td>{item1.class}</Table.Td>
        </Table.Tr>
        {/* ... more rows */}
    </Table.Tbody>
</Table>
```

### build rows in a separate variable

- from an array of object:

```tsx
const rows = items.map((item) => (
    <Table.Tr>
        <Table.Td>{item.name}</Table.Td>
        <Table.Td>{item.level}</Table.Td>
        <Table.Td>{item.class}</Table.Td>
    </Table.Tr>
))
```

- from an array of arrays:

```tsx
const rows = items.map((item) => (
    <Table.Tr>
        <Table.Td>{item[0]}</Table.Td>
        <Table.Td>{item[1]}</Table.Td>
        <Table.Td>{item[2]}</Table.Td>
    </Table.Tr>
))
```

We then use them in _Tbody_:

```tsx
<Table.Tbody>{rows}</Table.Tbody>
```

# Tables from data prop



In this version, the `<Table>` inner-markup is generated automatically, from the data we pass to the `data` prop:

```tsx
<Table data={data} />
```

The data prop, of type `TableData`, mainly provides the `head` and `body` properties:

- `body` provides the rows: an array of arrays (an item is an array)
- `head` provides the headers.
- The `caption` property defines the table's title

```tsx
const data: TableData = {
    caption: "Some elements from periodic table",
    head: ["Element position", "Atomic mass", "Symbol", "Element name"], // headers
    body: [
        // items
        [6, 12.011, "C", "Carbon"],
        [7, 14.007, "N", "Nitrogen"],
        [39, 88.906, "Y", "Yttrium"],
        [56, 137.33, "Ba", "Barium"],
        [58, 140.12, "Ce", "Cerium"],
    ],
}
```

# TextInput



_TextInput_ is an abstraction over `<input type=text>`. It inherits most props from _Input_. We describe both in this section.

controlled:

```tsx
<TextInput
    label="Summary"
    placeholder="What did you work on?"
    // state
    value={summary}
    onChange={(event) => setSummary(event.currentTarget.value)}
/>
```

uncontrolled:

```tsx
<TextInput
    label="Email"
    placeholder="john-appple@example.com"
    // ref
    ref={mailInput}
/>
```

### props

- Set the main label with `label`. A label describes the input's purpose.
- Add an optional secondary label with `description`
- Add some placeholder text with `placeholder`.
- Add icons, visually inside the input, with `leftSection` and `rightSection`.
- Mark the input as `required`. Mantine automatically adds an asterisk, unless we remove it with `withAsterisk`.
- shrink or enlarge the input with `size`.

### others

- Add `data-autofocus` to focus on mount

# NumberInput



_NumberInput_ uses a `<input type=text>` under the hood: this allows Mantine to have more flexibility in displaying non-number characters compared to the HTML `<input type=number>`.

For example, Mantine can display a thousand separator, even a custom one.

Mantine's underlying managed value differs from what is displayed: Mantine tries to manage an underlying _number_ every time it makes sense. The thousand separators are not part of the underlying managed value.

Yet, the managed value is not always a _number_: it is a _string_ when Mantine cannot resolve it to a _number_ without ambiguity:

- the input is empty: ""
- the input is a standalone negative sign: "-"
- the input's number is too big or too small to fit in as a JS _number_
- the input has a trailing decimal separator: `0.`
- the input has a trailing decimal zero, such as `0.00`

Otherwise the value is a _number_.

As such, we work with a _string_ and _number_ type union:

```tsx
// NumberInput managed value:
const [value, setValue] = useState<string | number>("")
return <NumberInput value={value} onChange={setValue} />
```

### options and overrides

- forbid decimal numbers with `allowDecimal={false}`. (They are allowed by default).
- forbid negative numbers with `allowNegative={false}`. (They are allowed by default.)
- clamp the value in the range between `min` and `max`. We determine how the value should clamp with `clampBehavior`:
    - Clamp after input on `blur` (after exiting the input). This is the default.
    - Forbid values outside the limits at all times with `strict`.
    - Never clamp with `none`

### other options (_Input_)

As an _Input_, it supports _label_, _description_ (secondary label) and _placeholder_.

# FileInput



FileInput is a control that triggers the OS dialog to pick a file.

On iOS, we first choose between taking a photo, opening the Photos library, or choosing a file from the Files app.

The control shows information about the current selection.

### synopsis

We work with the selected file by providing a handler to `onChange`:

- The handler receives a _File_ object (or a _File_ array).
- The handler is called:
    - when the user closes the platform's native File picker
    - or when the user clears the selection.

```tsx
<FileInput
    onChange={onChange}
    placeholder="Reference Image"
    variant="unstyled"
    leftSection={<IconPhoto size={18} stroke={1.5} />}
    size="xs"
    maw={150}
    clearable
/>
```

### main options

- Enable multiple file selection with `multiple`. It defaults to false.
- Restrict selection to a given file type with `accept`, such as `"image/png"`
- Add a clear button on the right with `clearable`

### other techniques

- Limit the input's max width to truncate long file names.
- Add a file icon to the _leftSection_.
- Opt for the _unstyled_ variant which looks similar to a _transparent_ variant: there is no border or background fill.
- Shrink the control with _size_.

# Date and Time inputs



## overview

### setup

Mantine offers the date and time components in a separate package. We must import a separate stylesheet:

```bash
npm install @mantine/dates dayjs
```

```ts
import "@mantine/dates/styles.css"
```

### date as strings

Mantine's date and time components natively work with date strings formatted as follows:

- `2026-04-24` (ISO compliant)
- `16:14:00` pr `16:14` (ISO compliant)
- `2026-04-24 16:14:00` (sometimes called _SQL format_)

While full dates are represented with _SQL format_ strings, the components are compatible with ISO date strings: we can store an ISO date string in state, initialize the component with it and update the component with it:

- `2026-04-24T13:10:22.592Z`

In the following examples, we work with dates stored in state as _ISO strings_ rather than _SQL strings_

### luxon

In the following examples, we sometimes use Luxon's `DateTime` helper to create and/or format dates.

## DateTimePicker

_DateTimePicker_ aims to collect a full date and time string, using both a calender style picker and a time input.

It supports _valueFormat_ to customize the displayed date. It does not dictate how the dates are stored.

We provide the underlying date in _value_ and _onChange_. While it natively works with SQL format strings, we can also provide the date as an ISO string:

```tsx
// 1.0 init
const [createdAtISO, setCreatedAtISO] = useState(new Date().toISOString())
// '2026-04-24T13:10:22.592Z'
```

```tsx
// 2.0 in use
<DateTimePicker
    // what is shown in the input
    // e.g. April 24 — 16:14
    valueFormat="MMMM DD [—] HH:mm"
    // controlled value, compatible with ISO
    value={completedAtIso}
    // on change, the control provides a SQL formatted date
    // e.g. 2026-04-24 16:14:00
    onChange={(dateTimeSql) => {
        if (!dateTimeSql) return
        setCompletedAtIso(new Date(dateTimeSql).toISOString())
    }}
    // input label
    label="Completed at"
/>
```

## TimeInput

TimeInput works with `HH:mm`, `HH:mm:ss` and compatible variants. Note that those formats are ISO compliant:

```tsx
const initTime = DateTime.local().toFormat("HH:mm")
const [timeIso, setTimeIso] = useState(initTime)
```

The event is of type _React.ChangeEvent_:

```tsx
// "HH:mm"
<TimeInput
    label="Time"
    value={timeIso}
    onChange={(event) => {
        setTimeIso(event.target.value)
    }}
/>
```

## DatePickerInput

DatePickerInput is only concerned about the date part of the full date, aka the the `yyyy-MM-dd` part:

```tsx
const initDate = DateTime.local().toFormat("yyyy-MM-dd")
const [datePart, setDatePart] = useState(initDate)
```

Note: _onChange_ receive the candidate date part as a string:

```tsx
// "yyyy-MM-dd"
<DatePickerInput
    label="Date"
    value={datePart}
    onChange={(datePart) => {
        // 2026-04-24
        if (datePart) {
            setDatePart(datePart)
        }
    }}
/>
```

# Native Select



An abstraction over a `<select>` element, with inner `<option>` elements.

Instead of adding explicit markup, we define options and provide them to _NativeSelect_ (through the _data_ prop):

```tsx
<NativeSelect data={data} />
```

For each option, we provide a _label_ and a _value_:

```ts
const data = [
    { label: "Death Knight", value: "deathKnight" },
    { label: "Demon Hunter", value: "demonHunter" },
]
```

### (fallback) use the value as a label

If the _value_ can work as a _label_, or if we want to surface the _value_ directly in the UI, we can provide an array of raw strings. The strings are used both as values and labels:

```ts
const data = ["deathKnight", "demonHunter"]
```

# Select



_Select_ is more capable than _NativeSelect_:

- The dropdown keeps Mantine style and can be customized
- The list of options is searchable

# SegmentedControl



Pick a value among a set of options. The options always stay on screen (radio button).

The selected option is highlighted with an overlay. As we change the selection, Mantine moves the overlay with an animation.

Instead of explicit markup, we define the options and provide them to _SegmentedControl_. For each option, we provide:

- The `label` is the user-facing description: It is a string, or a React node, in particular when we want to add an icon.
- The `value` is the option's string identifier. It must conform to the type union provided at the component level.

The state holds the selected identifier. The initial value determines which option is selected at the start:

```tsx
type AIModel = "GPT" | "GEMINI"
const [model, setModel] = useState<AIModel>("GPT")

<SegmentedControl<AIModel>
    value={model}
    onChange={(v) => setModel(v)}
    data={[
        { label: "ChatGPT", value: "GPT" },
        { label: "Gemini", value: "GEMINI" },
    ]}
/>
```

# Button



An abstraction over a \<button\>.

### variants

- Pick a `variant`:
    - _filled_ uses bright colors. (default)
    - _default_
    - _light_ uses toned-down colors.
    - _outline_
    - _subtle_
    - _gradient_

### button-specific props

- Pick the button's primary `color`. It defaults to the theme's _primaryColor_, aka Mantine's blue. It applies to several parts of the button, such as the border, the background and sometimes the text, unless the text is white or black.
- Opt for a fluid button (fill the container) with `fullWidth`.
- Opt for compact version with `size`, which changes the font size, the height and the horizontal padding.
- `gradient`, when using the _gradient_ variant, sets the gradient's colors and direction,.

### other options

- `disabled`, sets the appearance and behavior to disabled. the disabled
  appearance is the same across all variants.
- `leftSection`, `rightSection`, for example for an icon.
- Show the loading spinner appearance (and disable the button) with `loading`. We add props to the loader with `loaderProps` (see Loader component).

```tsx
<Button rightSection={<IconDownload size={14} />}>Download</Button>
```

### Button not submitting form by default

Mantine adds _type=button_ on the underlying \<button\>. It prevents the
button from triggering the form submit, when inside a \<form\>. We set _type=submit_ if needed.

### providing an onClick handler

The handler receives the click event, of type `React.MouseEvent<HTMLButtonElement, MouseEvent>`.

We can ignore the event argument and perform an action regardless.

The handler is not supposed to return anything.

If we define the handler in a separate location, we can annotate its type:

```tsx
React.MouseEvent<HTMLButtonElement> => void;
// shortcut version:
React.MouseEventHandler<HTMLButtonElement>
```

# Button.Group



We create a button cluster that glues up the buttons together, either horizontally (default) or vertically:

```tsx
<Button.Group>
    <Button variant="default">First</Button>
    <Button variant="default">Second</Button>
    <Button variant="default">Third</Button>
</Button.Group>
```

# ActionIcon



### icon as a button

ActionIcon serves the "icon as a button" pattern. It requires a self-explanatory icon, which makes the text label not strictly needed. For example, the "trash" icon unambiguously conveys the meaning of the "delete" action.

Technically, the icon is added as child of _ActionIcon_:

```tsx
<ActionIcon>
	<IconMail size={14} stroke={...}/>
</ActionIcon>
```

The child icon now behaves like a button, and follows the _variant_ appearance. To get a naked icon effect,
we select the _subtle_ or _transparent_ variants.

We can set `size` at the ActionIcon level: it impacts the hover and active zone, and the
icon scale.