{"record":{"id":"0dc58c7a43bbdd52","repo":"react-navigation/react-navigation","slug":"the-below-icon-label-position-for-tab-bar-is-onl","errorCode":null,"errorMessage":"The 'below-icon' label position for tab bar is only supported when 'tabBarPosition' is set to 'top' or 'bottom' when using the 'uikit' variant.","messagePattern":"The 'below-icon' label position for tab bar is only supported when 'tabBarPosition' is set to 'top' or 'bottom' when using the 'uikit' variant\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/bottom-tabs/src/views/BottomTabBar.tsx","lineNumber":223,"sourceCode":"\n  const tabBarPosition = useTabBarPosition(focusedOptions);\n\n  if (\n    tabBarVariant === 'material' &&\n    tabBarPosition !== 'left' &&\n    tabBarPosition !== 'right'\n  ) {\n    throw new Error(\n      \"The 'material' variant for tab bar is only supported when 'tabBarPosition' is set to 'left' or 'right'.\"\n    );\n  }\n\n  if (\n    tabBarLabelPosition === 'below-icon' &&\n    tabBarVariant === 'uikit' &&\n    (tabBarPosition === 'left' || tabBarPosition === 'right')\n  ) {\n    throw new Error(\n      \"The 'below-icon' label position for tab bar is only supported when 'tabBarPosition' is set to 'top' or 'bottom' when using the 'uikit' variant.\"\n    );\n  }\n\n  const insets = useSafeAreaInsets();\n  const isKeyboardShown = useIsKeyboardShown();\n\n  const onHeightChange = React.use(BottomTabBarHeightCallbackContext);\n\n  const shouldShowTabBar = !(tabBarHideOnKeyboard && isKeyboardShown);\n\n  const visibilityAnimationConfigRef = React.useRef(\n    tabBarVisibilityAnimationConfig\n  );\n\n  React.useEffect(() => {\n    visibilityAnimationConfigRef.current = tabBarVisibilityAnimationConfig;\n  });","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/react-navigation/react-navigation/blob/ab1319d6bbf05eae8dc25e33cbf4dc56494e0f0c/packages/bottom-tabs/src/views/BottomTabBar.tsx#L205-L241","documentation":"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.","triggerScenarios":"screenOptions include tabBarVariant=\"uikit\" and tabBarLabelPosition=\"below-icon\" (or left at its 'below-icon' default) while tabBarPosition is 'left' or 'right'.","commonSituations":"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'.","solutions":["Set tabBarLabelPosition=\"beside-icon\" in screenOptions when using the uikit variant with tabBarPosition 'left' or 'right'.","If below-icon labels are required, switch tabBarPosition to 'top' or 'bottom'.","Or use a different tabBarVariant that supports below-icon labels in side positions.","Audit screenOptions so variant, position, and labelPosition are set as a consistent group."],"exampleFix":"// before\n<Tab.Navigator screenOptions={{ tabBarVariant: 'uikit', tabBarPosition: 'left' }}>\n// after\n<Tab.Navigator screenOptions={{ tabBarVariant: 'uikit', tabBarPosition: 'left', tabBarLabelPosition: 'beside-icon' }}>","handlingStrategy":"validation","validationCode":"function validateTabBarOptions(opts) {\n  const side = opts.tabBarPosition === 'left' || opts.tabBarPosition === 'right';\n  const belowIcon = (opts.tabBarLabelPosition ?? 'below-icon') === 'below-icon';\n  if (opts.tabBarVariant === 'uikit' && side && belowIcon) {\n    throw new Error(\"uikit side bar requires tabBarLabelPosition 'beside-icon'\");\n  }\n}\nvalidateTabBarOptions({ tabBarVariant: 'uikit', tabBarPosition: 'right' }); // throws (default label position)","typeGuard":"function isUikitSideBarValid(opts: { tabBarVariant?: string; tabBarPosition?: string; tabBarLabelPosition?: string }): boolean {\n  const side = opts.tabBarPosition === 'left' || opts.tabBarPosition === 'right';\n  return !side || opts.tabBarVariant !== 'uikit' || opts.tabBarLabelPosition === 'beside-icon';\n}","tryCatchPattern":null,"preventionTips":["When switching to a side position with the uikit variant, always set tabBarLabelPosition: 'beside-icon'.","Remember tabBarLabelPosition defaults to 'below-icon' — an unset option can still trigger this.","Validate variant, position, and labelPosition together in one helper.","Test layouts after changing tab bar position."],"tags":["react-navigation","configuration","tab-bar","invalid-option-combination"],"backgroundTag":"invalid-prop-combination","analyzedSha":"ab1319d6bbf05eae8dc25e33cbf4dc56494e0f0c","analyzedAt":"2026-08-31T14:46:19.520Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}