‹ Lifecycle and events

Hook

useScreenEvent()

An event of the screen the component is in, by its name in listeners and navigation.on: only this screen's. The handler can change on every render.

SectionLifecycle and eventsDraftDocumented, not reviewed yet: the API can change.

Import

import { useScreenEvent } from '@apexnative/navigation';

useScreenEvent listens to one event of the screen the component is in, by its name: the sheet the screen is in was dragged, the screen left its stack, a keyboard shortcut was pressed. It hears only this screen's events, and stops when the component unmounts. The other screen hooks are made of it.

Usage

src/screens/Filters.tsx

import { useState } from 'react';
import { useScreenEvent } from '@apexnative/navigation';

export function Filters() {
  const [expanded, setExpanded] = useState(false);

  useScreenEvent('sheetDetentChanged', ({ detent }) => {
    setExpanded(detent === 'large');
  });

  return expanded ? <AllFilters /> : <MainFilters />; // your own
}

Filters shows in a sheet. When the user drags the sheet to full height, it shows all the filters; dragged back down, the main ones.

Signature

function useScreenEvent<Name extends ScreenEventName>(
  name: Name,
  handler: (event: NavigationEvents[Name]) => void
): void

Defined in src/api/hooks/screenHooks.ts ↗

name is the name of the event, the same as in listeners of createNavigation and in navigation.on. Only the events that belong to a screen are allowed: those that carry screen, and accessoryPlacementChanged. The type of name lists them, and the editor completes them.

handler gets the event, typed by its name. The events of a screen carry it as screen: { id, name }. The handler can change on every render: the call goes to the one of the last render, so it reads the current props and state, without useCallback.

It returns nothing.

The events of a screen

Event	When	Its own hook
screenWillAppear	The screen starts to come in.
screenDidAppear	The screen is in place.	useScreenAppear
screenDidDisappear	The screen is covered, or has left.	useScreenDisappear
screenPopped	The screen left its stack: back, a swipe, pop.
buttonPressed	A button of its top bar or toolbar.	useNavigationButton
modalDismissed	The modal it is in is gone.
modalDismissAttempted	A swipe tried to close its modal while it holds the user.	usePreventLeave
searchChanged, searchSubmitted, searchCancelled, searchSuggestionPicked	Its search field.	useSearchBar
sheetDetentChanged	iOS The user dragged its sheet to a detent.
keyCommandPressed	iOS A keyboard shortcut of its options.
titleRenamed	iOS The user renamed its title.
previewCompleted	iOS A preview opened into it.
accessoryPlacementChanged	iOS 26+: the tab bar accessory this component renders moved.

Where an event has its own hook, the hook reads better; useScreenEvent is for the others.

screenWillAppear

The one appearance event without a hook of its own. It comes when the move starts, before the screen is in place: the moment to start what should be ready while the screen slides in.

useScreenEvent('screenWillAppear', () => {
  prefetchDetails(); // your own
});

screenPopped

Comes when the screen leaves its stack, whatever took it out: the back button, a swipe, pop. Unlike screenDidDisappear, it doesn't come when the screen is only covered.

useScreenEvent('screenPopped', () => {
  saveDraft(text); // your own step
});

Pitfalls

• Only this screen's events. An event of another screen never reaches the handler, even of a screen with the same name. For the events of every screen, or the events that belong to no screen (tabSelected, stateChanged), use useNavigationEvent.
• A component of the bar is a screen of its own. A component shown as a title, a button or a search results screen is registered in screens and is a screen of its own: there the hook hears that component's events, not the events of the screen whose bar it is in.
• Events while unmounted are lost. The hook listens from the first effect of the component to its unmount. An event that came before is not replayed.
• Outside a screen the hook throws "This hook is for the screens of createNavigation".

Compared with React Navigation

The nearest is navigation.addListener(name, …) in a useEffect, which returns the function that stops it. Here it is one call, without dependencies and without cleanup. The names differ: React Navigation's focus, blur, beforeRemove, transitionStart are events of its own navigators; here the events come from the platform, with the names in the table above.

See also

• Every event and where to listen.
• useNavigationEvent.

Generated from the types and their comments. Edit the source ↗