Get started
Introduction
Installation
Your first app
Tutorials
Fission tutorials
Handle iOS safe areas, notches and the home indicator
Core concepts
Components
State and effects
Protected routes
Server-side rendering
Styling
Testing
Deployment
Reference
API reference
Cookbook
Fission 0.16.0
Documentation version
Read the changelog →

Handle iOS safe areas, notches and the home indicator

Build a delivery handover form around real host insets, keeping long input reachable inside a scrolling region.
iOS

What you will build

Place the handover content inside SafeArea without inventing padding for named iPhone models.
Put the background outside the safe area and scrollable content inside it
Prepare a snapshot from actual recipient and instruction input
Check physical insets and keyboard behaviour as separate concerns
A screen can fit within its window and still place a button beneath the home indicator. The window's bounds describe the available surface; its safe-area insets describe the part of that surface the host asks ordinary content to avoid. These are different inputs, so a fixed bottom padding is not a substitute for the inset.
We will build a delivery handover form with a long note and a final review action. This gives us something useful to inspect: the heading must clear the status area, the note must remain editable and the last action must remain reachable as the available space changes.

Create the shared app

Follow iOS setup if Xcode and the Rust targets are not installed.
cargo install cargo-fission
fission init ios-handle-ios-safe-areas-notches-and-the-home-indicator
cd ios-handle-ios-safe-areas-notches-and-the-home-indicator
fission add-target ios --project-dir .
cargo add serde_yaml
Keep the generated src/main.rs. Replace the shared library with the files below so that the native app runs the same form as the Web preview.

Run the finished example

fission run --target ios --project-dir .

1. Put the safe boundary outside the scrollable content

The nesting is deliberate. The background belongs to the outer container, whilst SafeArea insets the scrollable content. Ordinary spacing comes from theme tokens inside that boundary. It therefore remains useful spacing on every device rather than being an accidental correction for one iPhone.
The form's draft is local UI memory. Preparing a handover copies a snapshot into application state; it does not claim to send a delivery request or persist it. Keeping those meanings separate makes the visible result match what the code actually does.
{"id":"fission-tabs-1","tabs":[{"index":0,"label":"src/app.rs","value":"src-app-rs"},{"index":1,"label":"src/app/state.rs","value":"src-app-state-rs"},{"index":2,"label":"src/app/screen.rs","value":"src-app-screen-rs"},{"index":3,"label":"src/i18n.rs","value":"src-i18n-rs"},{"index":4,"label":"src/lib.rs","value":"src-lib-rs"},{"index":5,"label":"preview/lib.rs","value":"preview-lib-rs"},{"index":6,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"},{"index":7,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}]}
{"id":"fission-tabs-1","index":0,"label":"src/app.rs","value":"src-app-rs"}
pub mod screen;
pub mod state;
pub use screen::HandoverScreen;
pub use state::HandoverState;
{"id":"fission-tabs-1","index":1,"label":"src/app/state.rs","value":"src-app-state-rs"}
use fission::prelude::*;

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Handover {
    pub recipient: String,
    pub instructions: String,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct HandoverState {
    pub prepared: Option<Handover>,
    pub locale: Locale,
}

impl Default for HandoverState {
    fn default() -> Self {
        Self {
            prepared: None,
            locale: Locale::from("en-US"),
        }
    }
}

impl GlobalState for HandoverState {}
{"id":"fission-tabs-1","index":2,"label":"src/app/screen.rs","value":"src-app-screen-rs"}
use super::state::{Handover, HandoverState};
use fission::prelude::*;

fission_component! {
    pub HandoverScreen<HandoverState> {
        state {
            recipient: String = String::new(),
            instructions: String = String::new(),
        }
    }
    view(form, state, cx) {
        let tokens = &cx.view.env().theme.tokens;
    } => Container(
        SafeArea(
            child: Scroll(
                child: Container(Column(gap: tokens.spacing.m, children: [
                    Text(cx.tr("handover.title")).size(tokens.typography.heading2_size),
                    Text(cx.tr("handover.explanation")).color(tokens.colors.text_secondary),
                    Row(gap: tokens.spacing.s, children: [
                        Button(
                            child: Text(cx.tr("language.english")), key: "english",
                            on_press: reduce { state.locale = Locale::from("en-US"); },
                        ),
                        Button(
                            child: Text(cx.tr("language.spanish")), key: "spanish",
                            on_press: reduce { state.locale = Locale::from("es-ES"); },
                        ),
                    ]),
                    FormControl(
                        label: Some(cx.tr("handover.recipient")),
                        required: true,
                        child: TextInput(
                            value: form.recipient.clone(),
                            bind(on_input): to(form.recipient),
                            keyboard_type: TextInputType::Name,
                            semantics_identifier: Some("handover.recipient".into()),
                        ),
                    ),
                    Text(cx.tr("handover.guidance")),
                    TextInput(
                        value: form.instructions.clone(),
                        bind(on_input): to(form.instructions),
                        label: Some(TextContent::Key("handover.instructions".into())),
                        multiline: true,
                        keyboard_type: TextInputType::Multiline,
                        text_input_action: TextInputAction::Newline,
                        semantics_identifier: Some("handover.instructions".into()),
                    ),
                    Text(cx.tr("handover.review_hint")).color(tokens.colors.text_secondary),
                    Button(
                        child: Text(cx.tr("handover.prepare")), key: "prepare-handover",
                        disabled: form.recipient.trim().is_empty() || form.instructions.trim().is_empty(),
                        on_press: reduce {
                            state.prepared = Some(Handover {
                                recipient: form.recipient.trim().to_owned(),
                                instructions: form.instructions.trim().to_owned(),
                            });
                        },
                    ),
                    if let Some(handover) = &state.prepared {
                        Column(gap: tokens.spacing.s, children: [
                            Text(cx.tr("handover.prepared")).weight(tokens.typography.font_weight_semibold),
                            Text(handover.recipient.clone()),
                            Text(handover.instructions.clone()),
                            Text(cx.tr("handover.session_only")).color(tokens.colors.text_secondary),
                        ])
                    },
                ]))
                .padding_all(tokens.spacing.l),
            ),
        ),
    )
    .bg(tokens.colors.surface)
}
{"id":"fission-tabs-1","index":3,"label":"src/i18n.rs","value":"src-i18n-rs"}
use fission::i18n::{Locale, TranslationBundle};
use fission::prelude::*;
use std::collections::HashMap;

pub fn create_env() -> Env {
    let mut env = Env::default();
    env.locale = Locale::from("en-US");
    for (locale, source) in [
        ("en-US", include_str!("../i18n/en-US.yaml")),
        ("es-ES", include_str!("../i18n/es-ES.yaml")),
    ] {
        let messages: HashMap<String, String> =
            serde_yaml::from_str(source).expect("valid handover translations");
        env.i18n.add_bundle(TranslationBundle {
            locale: Locale::from(locale),
            messages,
        });
    }
    env
}

pub fn sync_env(state: &crate::app::HandoverState, env: &mut Env) {
    env.locale = state.locale.clone();
}
{"id":"fission-tabs-1","index":4,"label":"src/lib.rs","value":"src-lib-rs"}
pub mod app;
mod i18n;

use app::{HandoverScreen, HandoverState};
use fission::prelude::*;

#[cfg(not(any(target_arch = "wasm32", target_os = "android", target_os = "ios")))]
pub fn run_desktop() -> anyhow::Result<()> {
    DesktopApp::<HandoverState, _>::new(HandoverScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
}

#[cfg(any(target_os = "android", target_os = "ios"))]
pub fn run_mobile() -> anyhow::Result<()> {
    MobileApp::<HandoverState, _>::new(HandoverScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
}

#[cfg(target_os = "android")]
#[no_mangle]
fn android_main(app_handle: AndroidApp) {
    let _ = MobileApp::<HandoverState, _>::new(HandoverScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run_with_android_app(app_handle);
}

#[cfg(target_arch = "wasm32")]
#[wasm_bindgen::prelude::wasm_bindgen(start)]
pub fn run_web() -> Result<(), wasm_bindgen::JsValue> {
    console_error_panic_hook::set_once();
    WebApp::<HandoverState, _>::new(HandoverScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
        .map_err(|error| wasm_bindgen::JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1","index":5,"label":"preview/lib.rs","value":"preview-lib-rs"}
mod app;
mod i18n;

use fission::prelude::*;
use wasm_bindgen::prelude::*;

#[wasm_bindgen(start)]
pub fn run() -> Result<(), JsValue> {
    console_error_panic_hook::set_once();
    WebApp::<app::HandoverState, _>::new(app::HandoverScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .mount("#fission-web-mount")
        .run()
        .map_err(|error| JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1","index":6,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"}
handover.title: "Prepare a delivery handover"
handover.explanation: "Keep the recipient, delivery instructions and final action reachable on the device you are using."
handover.recipient: "Who will receive the delivery?"
handover.guidance: "Include the entrance, access arrangements and where the parcel can safely be left. Avoid including access codes in a shared note."
handover.instructions: "Delivery instructions"
handover.review_hint: "Review the instructions before preparing the handover. Long notes remain part of the scrollable page."
handover.prepare: "Prepare handover"
handover.prepared: "Prepared handover"
handover.session_only: "Prepared for this session; nothing has been sent or saved to disk."
language.english: "English"
language.spanish: "Español"
{"id":"fission-tabs-1","index":7,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}
handover.title: "Preparar una entrega"
handover.explanation: "Mantén accesibles el destinatario, las instrucciones y la acción final en el dispositivo que estés usando."
handover.recipient: "¿Quién recibirá la entrega?"
handover.guidance: "Incluye la entrada, las condiciones de acceso y dónde se puede dejar el paquete de forma segura. Evita incluir códigos de acceso en una nota compartida."
handover.instructions: "Instrucciones de entrega"
handover.review_hint: "Revisa las instrucciones antes de preparar la entrega. Las notas largas siguen formando parte de la página desplazable."
handover.prepare: "Preparar entrega"
handover.prepared: "Entrega preparada"
handover.session_only: "Preparada para esta sesión; no se ha enviado ni guardado nada en disco."
language.english: "Inglés"
language.spanish: "Español"
{"id":"fission-tabs-1"}
Enter a recipient and a multi-line note. Prepare the handover, then change the draft. The prepared snapshot should remain unchanged until you prepare it again. Switch language and reduce the preview width; the final action must remain reachable by scrolling.
Show the app preview
Hide the app preview

2. Understand what SafeArea can and cannot infer

Fission's SafeArea reads Env.window_insets and lowers a padded layout box. It does not identify an iPhone model, guess the notch's height or add a second copy of the inset to every child. Wrapping this form once is sufficient; repeatedly wrapping descendants can apply the same host input more than once.
There are two consequences worth making explicit. Firstly, a browser preview whose host reports zero insets cannot demonstrate clearance around an iPhone's physical cutout. Secondly, the keyboard is not merely another name for a notch. SafeArea alone does not establish keyboard avoidance or that a focused field will be scrolled into view. The scrollable form provides a way to reach content, but the actual keyboard behavior still needs target testing.
Do not add a hard-coded "keyboard height" when a check fails. Establish which window metrics the host reports and whether the control is obscured, unreachable or merely outside the current scroll position. Those failures have different causes. See keyboard-aware forms for focus and text-editing behavior.
Use enough text to make the page scroll. Verify the first field, the final action and the prepared result rather than checking only the heading. Resizing the browser checks reflow and scroll reachability, not native inset delivery.
Show the app preview
Hide the app preview

3. Check the device boundary rather than a screenshot of it

fission doctor ios --project-dir .
fission devices --project-dir .
fission run --target ios --project-dir .
fission test --target ios --project-dir .
Use the simulator guide to select a notched iPhone, then repeat on an iPad and in landscape. Check both languages with the keyboard open and closed. Scroll to the final action and make sure it can be pressed without a system gesture taking precedence.
The generated launch test establishes that the host starts, not that these controls clear every inset. A physical-device pass remains useful because the status region, home indicator and system gestures are part of the behavior being checked. Record the device, orientation and text-size setting alongside the result.
The example keeps handovers in memory. Reloading clears them; that is independent of safe-area layout and should not be mistaken for a persistence failure.