App Header

For development, import AppHeader from @servicetitan/anvil2-ai-kit. For design, find it in the AI Kit Web Component Library file.

Options

AppHeader supports an optional centered title and two independent action clusters.

Title

title renders centered between the two action clusters with <h1> semantics — it’s the primary heading of the view the shell frames. Omit it for an action-only header; the flexible middle still reserves the centered space, whether or not a title fills it.

Actions

leadingActions render at the start (left in LTR) and trailingActions at the end. Reserve leadingActions for entry points into the surrounding layout — panel toggles, navigation — and trailingActions for surface-level controls, like minimize and close. Keep each action in the cluster it conventionally belongs to; don’t relocate a panel toggle to the trailing side or a window control to the leading side. Consumers rely on this placement staying consistent across every Carto surface, so avoid rearranging it in your implementation.

Behavior

The header adapts its title to available space and can present any action as disabled.

Title Truncation

The title is single-line and truncates with an ellipsis rather than wrapping or pushing the action clusters. Its center shifts toward the side with fewer actions, since it fills the flexible space between both clusters.

Disabled Actions

Set disabled on an individual action to dim it and block interaction while keeping it in place — useful when a panel toggle has nothing to reveal yet.

Usage Guidelines

When to Use

Use the App Header when:

View identity – The experience needs a title bar that names the current view as its primary heading.
Shell-level actions – The experience needs panel toggles, navigation, or surface controls such as minimize and close.
Shell headers – An App Shell or Window needs content for its header region. The App Header also works on its own.

When not to use

Avoid using the App Header for:

Headings inside content – The App Header title is the primary heading of the view. Use a headline Text for headings within chat or panel content.
Actions with visible text labels – Every App Header action is an icon-only button whose label appears as a tooltip.

Keyboard Interaction

Users can navigate and activate header actions using standard keyboard controls.

Key	Description
Tab	Moves focus to the next action
Enter / Space	Activates the focused action

Patterns that use this component

Agentic Experience Shell — Identifies the experience and provides shell-level actions

Code

Implementation
AppHeader Props
AppHeaderAction

Common Examples

To use the AppHeader, pass a title and configured icon-button actions. It works standalone or in the header slot of AppShell.

import { AppHeader } from "@servicetitan/anvil2-ai-kit";
import { IconMenu, IconX } from "@servicetitan/anvil2-icons";

function ExampleComponent() {
  return (
    <AppHeader
      title="Conversation"
      leadingActions={[
        { id: "menu", icon: <IconMenu />, label: "Open navigation" },
      ]}
      trailingActions={[
        { id: "close", icon: <IconX />, label: "Close" },
      ]}
    />
  );
}

Actions

Each action renders as a ghost, icon-only Button. Its required label becomes the accessible name and tooltip.Set disabled to prevent an action.

Title

The title renders as the view’s h1. It fills the space between action clusters and truncates with an ellipsis before colliding with them.On a standalone, full-shell, or fullscreen window surface, the title is centered between the clusters. A docked Window start-aligns it automatically through app-surface context.

Window drag handle

Pass dragHandleProps from useAppSurface() to an action that moves a docked Window. The props are inert outside a docked window.

const { dragHandleProps } = useAppSurface();

<AppHeader
  leadingActions={[
    { icon: <IconGrip />, label: "Move window", dragHandleProps },
  ]}
/>;

Internationalization

AppHeader has no component-owned strings. Localize the title and each action label before passing them to the component.

React Accessibility

The title is the primary h1 for the framed view.
Every action requires a label used for its aria-label and tooltip.
Action buttons support pointer, touch, Enter, and Space through React Aria.

<AppHeader
  title="Conversation"
  leadingActions={leadingActions}
  trailingActions={trailingActions}
/>

`AppHeader` Props

The AppHeader accepts the following props and forwards remaining <header> attributes except children, native title, and style.

AppHeaderAction[]

Icon-button actions at the inline start.

string

Primary view title. Omit for an action-only header.

AppHeaderAction[]

Icon-button actions at the inline end.

const action: AppHeaderAction = {
  id: "close",
  icon: <IconX />,
  label: "Close",
  onPress: close,
};

`AppHeaderAction`

IconElement

required

Icon shown in the action button.

string

required

Accessible name and tooltip content.

boolean

default:"false"

Disables the action.

WindowDragHandleProps

Pointer and keyboard handlers that turn the action into a docked-window drag handle.

string

Stable React key. Defaults to label.

() => void

Handles action activation.

Concepts & Guidelines

Anvil2

Resources

App Header - Web

Options

Title

Actions

Behavior

Title Truncation

Disabled Actions

Usage Guidelines

When to Use

When not to use

Keyboard Interaction

Patterns that use this component

Code

Common Examples

Actions

Title

Window drag handle

Internationalization

React Accessibility

`AppHeader` Props

`AppHeaderAction`

​Options

​Title

​Actions

​Behavior

​Title Truncation

​Disabled Actions

​Usage Guidelines

​When to Use

​When not to use

​Keyboard Interaction

​Patterns that use this component

​Code

​Common Examples

​Actions

​Title

​Window drag handle

​Internationalization

​React Accessibility

​AppHeader Props

​AppHeaderAction

Options

Title

Actions

Behavior

Title Truncation

Disabled Actions

Usage Guidelines

When to Use

When not to use

Keyboard Interaction

Patterns that use this component

Code

Common Examples

Actions

Title

Window drag handle

Internationalization

React Accessibility

`AppHeader` Props

`AppHeaderAction`