react-navigation/react-navigation · error

The 'below-icon' label position for tab bar is only supporte

Error message

The 'below-icon' label position for tab bar is only supported when 'tabBarPosition' is set to 'top' or 'bottom' when using the 'uikit' variant.

What it means

BottomTabBar throws this when the 'uikit' tab bar variant is combined with a side (left/right) position while labels are set to 'below-icon'. The uikit side-bar rendering only supports labels beside icons, so 'below-icon' is rejected at render time rather than rendering an incorrect layout.

Source

Thrown at packages/bottom-tabs/src/views/BottomTabBar.tsx:223

  const tabBarPosition = useTabBarPosition(focusedOptions);

  if (
    tabBarVariant === 'material' &&
    tabBarPosition !== 'left' &&
    tabBarPosition !== 'right'
  ) {
    throw new Error(
      "The 'material' variant for tab bar is only supported when 'tabBarPosition' is set to 'left' or 'right'."
    );
  }

  if (
    tabBarLabelPosition === 'below-icon' &&
    tabBarVariant === 'uikit' &&
    (tabBarPosition === 'left' || tabBarPosition === 'right')
  ) {
    throw new Error(
      "The 'below-icon' label position for tab bar is only supported when 'tabBarPosition' is set to 'top' or 'bottom' when using the 'uikit' variant."
    );
  }

  const insets = useSafeAreaInsets();
  const isKeyboardShown = useIsKeyboardShown();

  const onHeightChange = React.use(BottomTabBarHeightCallbackContext);

  const shouldShowTabBar = !(tabBarHideOnKeyboard && isKeyboardShown);

  const visibilityAnimationConfigRef = React.useRef(
    tabBarVisibilityAnimationConfig
  );

  React.useEffect(() => {
    visibilityAnimationConfigRef.current = tabBarVisibilityAnimationConfig;
  });

View on GitHub (pinned to ab1319d6bb)

Solutions

1. Set tabBarLabelPosition="beside-icon" in screenOptions when using the uikit variant with tabBarPosition 'left' or 'right'.
2. If below-icon labels are required, switch tabBarPosition to 'top' or 'bottom'.
3. Or use a different tabBarVariant that supports below-icon labels in side positions.
4. Audit screenOptions so variant, position, and labelPosition are set as a consistent group.

Example fix

// before
<Tab.Navigator screenOptions={{ tabBarVariant: 'uikit', tabBarPosition: 'left' }}>
// after
<Tab.Navigator screenOptions={{ tabBarVariant: 'uikit', tabBarPosition: 'left', tabBarLabelPosition: 'beside-icon' }}>

function validateTabBarOptions(opts) {
  const side = opts.tabBarPosition === 'left' || opts.tabBarPosition === 'right';
  const belowIcon = (opts.tabBarLabelPosition ?? 'below-icon') === 'below-icon';
  if (opts.tabBarVariant === 'uikit' && side && belowIcon) {
    throw new Error("uikit side bar requires tabBarLabelPosition 'beside-icon'");
  }
}
validateTabBarOptions({ tabBarVariant: 'uikit', tabBarPosition: 'right' }); // throws (default label position)

function isUikitSideBarValid(opts: { tabBarVariant?: string; tabBarPosition?: string; tabBarLabelPosition?: string }): boolean {
  const side = opts.tabBarPosition === 'left' || opts.tabBarPosition === 'right';
  return !side || opts.tabBarVariant !== 'uikit' || opts.tabBarLabelPosition === 'beside-icon';
}

When it happens

Trigger: screenOptions include tabBarVariant="uikit" and tabBarLabelPosition="below-icon" (or left at its 'below-icon' default) while tabBarPosition is 'left' or 'right'.

Common situations: Migrating a bottom tab bar (below-icon default) to a side bar by only changing tabBarPosition; copying iOS-style (uikit) config from a top/bottom setup into a sidebar setup; forgetting that tabBarLabelPosition defaults to 'below-icon'.

Related errors

• The 'material' variant for tab bar is only supported when 't
• The '${customTabBarPosition}' position for the tab bar is no
• Menu item must have a 'menu' property defined: ${JSON.string
• Invalid item type: ${JSON.stringify(item)}. Valid types are
• Invalid item type: ${JSON.stringify(item)}. Valid types are

AI-assisted analysis of react-navigation/react-navigation@ab1319d6bb (2026-08-31). Data as JSON: /api/errors/0dc58c7a43bbdd52. Report an issue: GitHub.