# ModalHeader

A component that provides a consistent header section for Modal.

## Import

```tsx
import { ModalHeader } from '@coinbase/cds-mobile/overlays/modal/ModalHeader'
```

## Examples

ModalHeader provides a consistent header section for [Modal](/components/overlay/Modal). It displays a centered title with optional back and close buttons that integrate with Modal's context.

### Basics

Pass a `title` to display centered text. The close button automatically appears and uses Modal's `onRequestClose` handler.

```jsx
function BasicExample() {
  const [visible, setVisible] = useState(false);
  return (
    <>
      <Button onPress={() => setVisible(true)}>Open Modal</Button>
      <Modal onRequestClose={() => setVisible(false)} visible={visible}>
        <ModalHeader title="Account Settings" closeAccessibilityLabel="Close" />
        <ModalBody>
          <Text>Modal content goes here.</Text>
        </ModalBody>
      </Modal>
    </>
  );
}
```

### Back Button

Use `onBackButtonClick` to show a back arrow for multi-step flows. The back button appears on the left side of the header.

```jsx
function BackButtonExample() {
  const [visible, setVisible] = useState(false);
  return (
    <>
      <Button onPress={() => setVisible(true)}>Open Modal</Button>
      <Modal onRequestClose={() => setVisible(false)} visible={visible}>
        <ModalHeader
          title="Confirm Details"
          onBackButtonClick={() => setVisible(false)}
          backAccessibilityLabel="Go back"
          closeAccessibilityLabel="Close"
        />
        <ModalBody>
          <Text>Step 2 of 3</Text>
        </ModalBody>
      </Modal>
    </>
  );
}
```

### Title Only

Omit buttons by not providing `onBackButtonClick` and setting `hideCloseButton` on the Modal.

```jsx
function TitleOnlyExample() {
  const [visible, setVisible] = useState(false);
  return (
    <>
      <Button onPress={() => setVisible(true)}>Open Modal</Button>
      <Modal hideCloseButton onRequestClose={() => setVisible(false)} visible={visible}>
        <ModalHeader title="Processing..." />
        <ModalBody>
          <VStack alignItems="center" gap={3} padding={4}>
            <Spinner />
            <Text>Please wait while we process your request.</Text>
          </VStack>
        </ModalBody>
      </Modal>
    </>
  );
}
```

### Styling

#### Without Divider

Set `hideDividers` on Modal to remove the bottom border from the header.

```jsx
function NoDividerExample() {
  const [visible, setVisible] = useState(false);
  return (
    <>
      <Button onPress={() => setVisible(true)}>Open Modal</Button>
      <Modal hideDividers onRequestClose={() => setVisible(false)} visible={visible}>
        <ModalHeader title="No Divider" closeAccessibilityLabel="Close" />
        <ModalBody>
          <Text>The header has no bottom border.</Text>
        </ModalBody>
      </Modal>
    </>
  );
}
```

### Accessibility

Always provide `closeAccessibilityLabel` for the close button and `backAccessibilityLabel` when using the back button. These labels are announced by VoiceOver.

```jsx
function AccessibilityExample() {
  const [visible, setVisible] = useState(false);
  return (
    <>
      <Button onPress={() => setVisible(true)}>Open Modal</Button>
      <Modal onRequestClose={() => setVisible(false)} visible={visible}>
        <ModalHeader
          title="Transfer Funds"
          onBackButtonClick={() => setVisible(false)}
          backAccessibilityLabel="Go back to account selection"
          backAccessibilityHint="Returns to the previous step"
          closeAccessibilityLabel="Close transfer modal"
          closeAccessibilityHint="Cancels the transfer and returns to the main screen"
        />
        <ModalBody>
          <Text>Enter transfer details.</Text>
        </ModalBody>
      </Modal>
    </>
  );
}
```

### Composed Examples

#### Multi-Step Wizard

Use `onBackButtonClick` to navigate between steps in a wizard flow.

```jsx
function WizardExample() {
  const [visible, setVisible] = useState(false);
  const [step, setStep] = useState(1);
  const titles = ['Select Asset', 'Enter Amount', 'Confirm Transfer'];

  const handleClose = () => {
    setVisible(false);
    setStep(1);
  };

  return (
    <>
      <Button onPress={() => setVisible(true)}>Start Transfer</Button>
      <Modal onRequestClose={handleClose} visible={visible}>
        <ModalHeader
          title={titles[step - 1]}
          onBackButtonClick={step > 1 ? () => setStep((s) => s - 1) : undefined}
          backAccessibilityLabel="Go back"
          closeAccessibilityLabel="Close"
        />
        <ModalBody>
          <VStack gap={3}>
            <Text color="fgMuted">Step {step} of 3</Text>
            <Text>
              {step === 1 && 'Choose which asset to transfer.'}
              {step === 2 && 'Enter the amount you want to send.'}
              {step === 3 && 'Review and confirm your transfer.'}
            </Text>
          </VStack>
        </ModalBody>
        <ModalFooter
          primaryAction={
            <Button onPress={step < 3 ? () => setStep((s) => s + 1) : handleClose}>
              {step < 3 ? 'Continue' : 'Confirm'}
            </Button>
          }
          secondaryAction={
            <Button onPress={handleClose} variant="secondary">
              Cancel
            </Button>
          }
        />
      </Modal>
    </>
  );
}
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `backAccessibilityHint` | `string` | No | `-` | Sets an accessible hint or description for the back button. On web, maps to aria-describedby and lists the id(s) of the element(s) that describe the element on which the attribute is set. On mobile, a string that helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. |
| `backAccessibilityLabel` | `string` | No | `-` | Sets an accessible label for the back button. On web, maps to aria-label and defines a string value that labels an interactive element. On mobile, VoiceOver will read this string when a user selects the associated element. |
| `closeAccessibilityHint` | `string` | No | `-` | Sets an accessible hint or description for the close button. On web, maps to aria-describedby and lists the id(s) of the element(s) that describe the element on which the attribute is set. On mobile, a string that helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. |
| `closeAccessibilityLabel` | `string` | No | `-` | Sets an accessible label for the close button. On web, maps to aria-label and defines a string value that labels an interactive element. On mobile, VoiceOver will read this string when a user selects the associated element. |
| `onBackButtonClick` | `((event: GestureResponderEvent) => void)` | No | `-` | Handles back button press |
| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |
| `title` | `string` | No | `-` | Title of the Modal |


