Add support for iOS 26 subtitle in native stack

[fbeccaceci]

Description

This PR adds support for new properties introduced in iOS 26 as subtitle and largeSubtitle

Changes

• Update RNSScreenStackHeaderConfig.h and RNSScreenStackHeaderConfig.mm to support new iOS 26 subtitle

Screenshots / GIFs

Test code and steps to reproduce

<Stack.Screen
      name="root"
      component={MainScreen}
      options={{
        headerLargeTitle: true,
        headerTransparent: true,
        title: 'Future of Mobile Dev',
        // @ts-expect-error
        subtitle: '09/05/2025 • 5 min read',
      }}
    />

Inside of TestSubtitle.tsx you can pass to the screen option these new options:

 subtitle?: string;
  /**
   * Allows for setting text color of the subtitle.
   */
  subtitleColor?: ColorValue;
  /**
   * Customize font family to be used for the subtitle.
   */
  subtitleFontFamily?: string;
  /**
   * Customize the size of the font to be used for the subtitle.
   */
  subtitleFontSize?: number;
  /**
   * Customize the weight of the font to be used for the subtitle.
   */
  subtitleFontWeight?: string;
  /**
   * String that can be displayed in the header below title.
   */
  largeSubtitle?: string;
  /**
   * Allows for setting text color of the subtitle.
   */
  largeSubtitleColor?: ColorValue;
  /**
   * Customize font family to be used for the subtitle.
   */
  largeSubtitleFontFamily?: string;
  /**
   * Customize the size of the font to be used for the subtitle.
   */
  largeSubtitleFontSize?: number;
  /**
   * Customize the weight of the font to be used for the subtitle.
   */
  largeSubtitleFontWeight?: string;

Keep in mind that TypeScript will throw an error since the scope of this PR is just react-native-screens not react-navigation and the modification in the react-navigation submodule just aim to pass through the new props.

Checklist

• Included code example that can be used to test this change
• Updated TS types
• Updated documentation:
  • https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
  • https://github.com/software-mansion/react-native-screens/blob/main/native-stack/README.md
  • https://github.com/software-mansion/react-native-screens/blob/main/src/types.tsx
  • https://github.com/software-mansion/react-native-screens/blob/main/src/native-stack/types.tsx
• Ensured that CI passes

[kkafar]

This looks very promising. I'll review #2987 first & jump into this one. I think we'll land it.

[johankasperi]

Nice work! After this is landed I think next step should be to add support for subtitleView: ReactElement and largeSubtitleView: ReactElement.

More info:
https://developer.apple.com/documentation/uikit/uinavigationitem/subtitleview?changes=_7&language=objc
https://developer.apple.com/documentation/uikit/uinavigationitem/largesubtitleview?changes=_7&language=objc

[kligarski]

You can also modify largeTitle independently from title, similar to how largeSubtitle overrides subtitle (docs). If we want to also add support for largeTitle, I'm thinking how are we going to name this property because currently largeTitle/headerLargeTitle is a boolean property. We can add some kind of suffix like headerLargeTitleText but if all other props would be just largeSubtitle, subtitle, title without the suffix, this would be a little bit inconsistent.

[fbeccaceci]

I reasoned on this as well while working on this PR. My personal opinion is that the most correct solution would be to turn largeTitle to string and make it work as it is supposed to, but this would break compatibility with older versions.

A solution to don't break the api could be to make largeTitle boolean | string and when true is passed as value just set it to the same value of title, allowing for a string to be passed if the user want's to have another value

[aledebla03]

Do you have any update on the expected arrival time?

[ajanuar]

Hi @kkafar will you review this PR?

[denissdubinin]

Hey @kkafar, any progress here?

[DvzZDev]

@kkafar Any news on this?

[joernroeder]

I'd love to see this too. custom implementations alter the blur effect in the background.

[jonathankfmn]

@kkafar any Progress?

[greinald]

Any progress on this?

[kligarski]

Hi. Unfortunately, as we're currently focused on new native stack implementation for v5, we have limited time and resources to review/add new features to the old implementation, especially if they are significant changes. In new native stack implementation, full subtitle/largeTitle customization will be supported but for v4 it's unlikely we'll proceed here. Soon we're going to update our contributing guidelines regarding adding new features: #4028.