EXEPERTAI LAB

Research alpha

Time Machine
EXEPERTAI LAB
GALLERY / COLLECTION
← Browse Astryx gallery
AppShell·hook·@astryxdesign/core

useAppShellMobile

Hook for reading and controlling AppShell mobile navigation state from descendants of AppShell. Use it for custom mobile nav triggers, closing the drawer after route changes, or coordinating AppShell-adjacent mobile experiences with the same breakpoint used by mobile nav.

Open in Playground @astryxdesign/core/AppShell

Signature

Call shape
useAppShellMobile()
Returns
NameType and behavior
isMobileboolean
Whether the current viewport is below the AppShell mobile navigation breakpoint. Use this to synchronize AppShell-adjacent mobile UI with the same breakpoint as mobile nav.
isMobileNavOpenboolean
Whether the AppShell-managed mobile navigation drawer is open.
mobileNavIdstring | undefined
DOM id of the mobile navigation drawer, set by AppShell. Point aria-controls of a custom toggle at this so screen-reader users know which element the toggle expands. Undefined outside an AppShell that manages the drawer.
toggleMobileNav() => void
Toggle the AppShell-managed mobile navigation drawer. No-ops when mobile nav is disabled.
openMobileNav() => void
Open the AppShell-managed mobile navigation drawer. No-ops when mobile nav is disabled.
closeMobileNav() => void
Close the AppShell-managed mobile navigation drawer.
isMobileNavEnabledboolean
Whether AppShell mobile navigation is enabled and managed by AppShell. False when mobileNav is false, there is no nav content, or a fully custom mobileNav ReactNode owns the drawer.
hasAutoToggleboolean
Whether AppShell auto-toggle behavior is enabled. False when mobileNav hasToggle is set to false; combine with isMobile and isMobileNavEnabled before rendering custom toggles.

Showcases and examples

1 documented example

useAppShellMobile — Custom Mobile Trigger

Custom mobile navigation trigger built with useAppShellMobile. The trigger consumes the surrounding AppShell context instead of rendering its own shell.

Preview loads on approachPreview loads on approach
Exact source · app-shell-mobile-hook-usage
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useAppShellMobile} from '@astryxdesign/core/AppShell';
import {Button} from '@astryxdesign/core/Button';
import {HStack, VStack} from '@astryxdesign/core/Layout';
import {Text} from '@astryxdesign/core/Text';

export default function AppShellMobileHookUsage() {
  const {
    closeMobileNav,
    isMobile,
    isMobileNavEnabled,
    isMobileNavOpen,
    openMobileNav,
  } = useAppShellMobile();

  if (!isMobileNavEnabled) {
    return (
      <VStack gap={2}>
        <Button label="Open navigation" variant="secondary" isDisabled />
        <Text type="body" color="secondary">
          No active AppShell mobile navigation context was detected. This hook
          returns safe defaults outside AppShell, or when the surrounding
          AppShell has mobile navigation disabled.
        </Text>
      </VStack>
    );
  }

  if (!isMobile) {
    return (
      <VStack gap={2}>
        <Button label="Open navigation" variant="secondary" isDisabled />
        <Text type="body" color="secondary">
          AppShell mobile navigation context is available. Narrow the viewport
          below the AppShell mobile breakpoint to make the custom trigger
          active.
        </Text>
      </VStack>
    );
  }

  return (
    <VStack gap={2}>
      <HStack gap={2} vAlign="center">
        <Button
          label={isMobileNavOpen ? 'Close navigation' : 'Open navigation'}
          variant="secondary"
          onClick={isMobileNavOpen ? closeMobileNav : openMobileNav}
        />
        <Text type="body" color="secondary">
          {isMobileNavOpen ? 'Mobile nav is open' : 'Mobile nav is closed'}
        </Text>
      </HStack>
      <Text type="body" color="secondary">
        This button controls the nearest AppShell mobile nav from context; in
        the docsite it opens and closes the surrounding page navigation.
      </Text>
    </VStack>
  );
}

Usage

Hook for reading and controlling AppShell mobile navigation state from descendants of AppShell. Use it for custom mobile nav triggers, closing the drawer after route changes, or coordinating AppShell-adjacent mobile experiences with the same breakpoint used by mobile nav.

  • Use inside the AppShell tree when building custom mobile navigation controls, route-aware nav items, or UI that should update at the same breakpoint as AppShell mobile nav.
  • Prefer MobileNavToggle for the standard hamburger trigger: use this hook when you need custom placement, styling, or extra behavior.
  • Call closeMobileNav after a custom mobile nav item changes route so the drawer dismisses cleanly.
  • Use as a general responsive primitive when the UI is not inside AppShell or does not need to align with AppShell mobile nav: use useMediaQuery instead.
  • Assume it throws outside AppShell. The hook returns safe defaults and no-op callbacks when no provider is present.