react-native-magic-tab-bar 1.0.1 → 2.0.1

package/src/MagicTabItem.tsx

@@ -1,32 +1,92 @@
-import { forwardRef, useEffect, type ReactNode } from 'react';
+import { forwardRef, memo, useCallback, useEffect, useMemo, type ReactNode } from 'react';
 import {
   Pressable,
   StyleSheet,
+  Text,
+  View,
   type GestureResponderEvent,
   type View as RNView,
 } from 'react-native';
 import Animated, {
   FadeIn,
+  FadeOut,
   LinearTransition,
   useAnimatedStyle,
   useSharedValue,
   withSpring,
 } from 'react-native-reanimated';
-import type { MagicTabBarTheme, MagicTabIconProps } from './types';
+import type {
+  MagicLabelMode,
+  MagicLabelPosition,
+  MagicTabBarTheme,
+  MagicTabIconProps,
+  MagicTabPressHandler,
+} from './types';
+
+declare const require: (moduleName: string) => unknown;
+
+/** Minimal shape we use from the optional `expo-haptics` module. */
+type HapticsModule = { selectionAsync?: () => void };
+
+/**
+ * `expo-haptics` is an optional peer dependency. We load it through a guarded
+ * `require` so the library still installs and runs without it — when it's
+ * absent, the `haptics` prop simply has no effect.
+ */
+const expoHaptics = (() => {
+  try {
+    return require('expo-haptics') as HapticsModule;
+  } catch {
+    return null;
+  }
+})();
 
 const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
 
-const SPRING = { mass: 0.6, damping: 18, stiffness: 180 } as const;
-const transition = LinearTransition.springify()
-  .mass(SPRING.mass)
-  .damping(SPRING.damping)
-  .stiffness(SPRING.stiffness);
+/** Fixed small icon size used by the compact "light" tab bar. */
+const LIGHT_ICON_SIZE = 20;
+
+/** Whether a `badge` value should render anything at all. */
+function hasBadge(badge: MagicTabItemProps['badge']): boolean {
+  return badge === true || (typeof badge === 'number' && badge > 0) || (typeof badge === 'string' && badge.length > 0);
+}
+
+/** Formats a numeric/string badge; numbers above 99 collapse to `99+`. */
+function formatBadge(badge: number | string): string {
+  return typeof badge === 'number' && badge > 99 ? '99+' : String(badge);
+}
 
 export interface MagicTabItemProps {
   /** Renders the icon. Provided automatically by `MagicTabs`. */
   icon: (props: MagicTabIconProps) => ReactNode;
-  /** Optional label shown while the tab is active. */
+  /** Optional label text. */
   label?: string;
+  /** When the label is shown: `'active'` (default), `'always'` or `'never'`. */
+  labelMode?: MagicLabelMode;
+  /** Whether the label sits to the right of the icon (default) or below it. */
+  labelPosition?: MagicLabelPosition;
+  /**
+   * Badge shown over the icon. `true` renders a dot; a number/string renders
+   * a count bubble (numbers above 99 show as `99+`). Falsy renders nothing.
+   */
+  badge?: number | string | boolean;
+  /** Dim the tab and block presses. */
+  disabled?: boolean;
+  /** Render as a raised, circular action ("FAB") button. */
+  variant?: 'action';
+  /**
+   * Compact "light" mode: small icon-only tab, no label. Provided by
+   * `MagicTabs`. Uses its own dedicated styles.
+   */
+  isLight?: boolean;
+  /** Fire a selection haptic on press. Requires `expo-haptics`. */
+  haptics?: boolean;
+  /** Route name, used for the press callbacks. Provided by `MagicTabs`. */
+  name?: string;
+  /** Called when the tab is pressed. */
+  onTabPress?: MagicTabPressHandler;
+  /** Called when the tab is long-pressed. */
+  onTabLongPress?: MagicTabPressHandler;
   /** Resolved theme. Provided automatically by `MagicTabs`. */
   theme: MagicTabBarTheme;
 
@@ -48,32 +108,225 @@ export interface MagicTabItemProps {
  * Each tab sizes to its content — just the icon when inactive, icon + label
  * when active — so the active label is never clipped, on any screen width.
  */
-export const MagicTabItem = forwardRef<RNView, MagicTabItemProps>(
-  function MagicTabItem({ icon, label, theme, isFocused, onPress, onLongPress }, ref) {
+export const MagicTabItem = memo(forwardRef<RNView, MagicTabItemProps>(
+  function MagicTabItem(
+    {
+      icon,
+      label,
+      labelMode = 'active',
+      labelPosition = 'right',
+      badge,
+      disabled = false,
+      variant,
+      isLight = false,
+      haptics = false,
+      name,
+      onTabPress,
+      onTabLongPress,
+      theme,
+      isFocused,
+      onPress,
+      onLongPress,
+    },
+    ref,
+  ) {
     const focused = Boolean(isFocused);
+    const { spring } = theme;
     const progress = useSharedValue(focused ? 1 : 0);
 
     useEffect(() => {
-      progress.value = withSpring(focused ? 1 : 0, SPRING);
-    }, [focused, progress]);
+      progress.value = withSpring(focused ? 1 : 0, spring);
+    }, [focused, progress, spring]);
+
+    // Rebuilt only when the theme's spring changes, so consumers can tune the
+    // layout animation's feel via `theme.spring`.
+    const transition = useMemo(
+      () =>
+        LinearTransition.springify()
+          .mass(spring.mass)
+          .damping(spring.damping)
+          .stiffness(spring.stiffness),
+      [spring.mass, spring.damping, spring.stiffness],
+    );
 
     const pillStyle = useAnimatedStyle(() => ({
       opacity: progress.value,
       transform: [{ scale: 0.8 + progress.value * 0.2 }],
     }));
 
+    const handlePress = useCallback(
+      (event: GestureResponderEvent) => {
+        if (haptics) expoHaptics?.selectionAsync?.();
+        onTabPress?.(name ?? '', focused);
+        onPress?.(event);
+      },
+      [haptics, onTabPress, name, focused, onPress],
+    );
+
+    const handleLongPress = useCallback(
+      (event: GestureResponderEvent) => {
+        onTabLongPress?.(name ?? '', focused);
+        onLongPress?.(event);
+      },
+      [onTabLongPress, name, focused, onLongPress],
+    );
+
+    const badgeVisible = hasBadge(badge);
+    const badgeIsDot = badge === true;
+
+    const iconWithBadge = (iconColor: string, size: number) => (
+      <View>
+        {icon({ focused, color: iconColor, size })}
+        {badgeVisible ? (
+          <View
+            pointerEvents="none"
+            style={[
+              styles.badge,
+              badgeIsDot && styles.badgeDot,
+              { backgroundColor: theme.badgeColor },
+            ]}
+          >
+            {badgeIsDot ? null : (
+              <Text
+                numberOfLines={1}
+                style={[styles.badgeText, { color: theme.badgeTextColor }]}
+              >
+                {formatBadge(badge as number | string)}
+              </Text>
+            )}
+          </View>
+        ) : null}
+      </View>
+    );
+
+    // ---- Raised circular action ("FAB") tab ----
+    if (variant === 'action') {
+      const size = theme.height - 6;
+      return (
+        <AnimatedPressable
+          ref={ref}
+          onPress={handlePress}
+          onLongPress={handleLongPress}
+          disabled={disabled}
+          accessibilityRole="button"
+          accessibilityState={{ selected: focused, disabled }}
+          style={[
+            styles.action,
+            {
+              width: size,
+              height: size,
+              borderRadius: size / 2,
+              backgroundColor: theme.actionColor,
+            },
+            disabled && styles.disabled,
+          ]}
+        >
+          {iconWithBadge(theme.actionIconColor, theme.iconSize + 2)}
+        </AnimatedPressable>
+      );
+    }
+
+    // ---- Normal tab ----
     const color = focused ? theme.activeColor : theme.inactiveColor;
-    const showLabel = focused && !!label;
 
+    // ---- Compact "light" tab: small icon only, no label ----
+    if (isLight) {
+      return (
+        <AnimatedPressable
+          ref={ref}
+          onPress={handlePress}
+          onLongPress={handleLongPress}
+          disabled={disabled}
+          accessibilityRole="tab"
+          accessibilityState={{ selected: focused, disabled }}
+          layout={transition}
+          style={[styles.itemLight, disabled && styles.disabled]}
+        >
+          <Animated.View
+            pointerEvents="none"
+            style={[
+              StyleSheet.absoluteFill,
+              { backgroundColor: theme.activePillColor, borderRadius: theme.radius },
+              pillStyle,
+            ]}
+          />
+          {iconWithBadge(color, LIGHT_ICON_SIZE)}
+        </AnimatedPressable>
+      );
+    }
+
+    const showLabel =
+      !!label && labelMode !== 'never' && (labelMode === 'always' || focused);
+
+    // ---- Bottom labels: Material Design 3 layout ----
+    // The active indicator ("pill") wraps only the icon as a capsule; the label
+    // sits below it. Following M3's `LABEL_VISIBILITY_SELECTED` behaviour, each
+    // item is centered as a group: unlabeled tabs are just a centered icon, and
+    // the active tab grows to icon + label (nudging its icon up a touch). The
+    // layout transition animates that shift smoothly. Indicator sizing follows
+    // M3's 64x32-over-24dp ratio, scaled to the theme's icon size.
+    if (labelPosition === 'bottom') {
+      const indicatorHeight = theme.iconSize + 10;
+      const indicatorWidth = theme.iconSize + 32;
+      return (
+        <AnimatedPressable
+          ref={ref}
+          onPress={handlePress}
+          onLongPress={handleLongPress}
+          disabled={disabled}
+          accessibilityRole="tab"
+          accessibilityState={{ selected: focused, disabled }}
+          layout={transition}
+          style={[styles.itemBottom, disabled && styles.disabled]}
+        >
+          <View
+            style={[
+              styles.indicatorWrap,
+              { width: indicatorWidth, height: indicatorHeight },
+            ]}
+          >
+            <Animated.View
+              pointerEvents="none"
+              style={[
+                StyleSheet.absoluteFill,
+                {
+                  backgroundColor: theme.activePillColor,
+                  borderRadius: indicatorHeight / 2,
+                },
+                pillStyle,
+              ]}
+            />
+            {iconWithBadge(color, theme.iconSize)}
+          </View>
+          {showLabel ? (
+            <Animated.Text
+              entering={FadeIn.duration(150)}
+              exiting={FadeOut.duration(120)}
+              numberOfLines={1}
+              style={[styles.labelBottom, { color, fontSize: theme.fontSize - 1 }]}
+            >
+              {label}
+            </Animated.Text>
+          ) : null}
+        </AnimatedPressable>
+      );
+    }
+
+    // ---- Right labels: floating pill wrapping icon + label ----
     return (
       <AnimatedPressable
         ref={ref}
-        onPress={onPress}
-        onLongPress={onLongPress}
+        onPress={handlePress}
+        onLongPress={handleLongPress}
+        disabled={disabled}
         accessibilityRole="tab"
-        accessibilityState={{ selected: focused }}
+        accessibilityState={{ selected: focused, disabled }}
         layout={transition}
-        style={[styles.pressable, focused && styles.pressableActive]}
+        style={[
+          styles.pressable,
+          focused && styles.pressableActive,
+          disabled && styles.disabled,
+        ]}
       >
         <Animated.View
           pointerEvents="none"
@@ -83,10 +336,11 @@ export const MagicTabItem = forwardRef<RNView, MagicTabItemProps>(
             pillStyle,
           ]}
         />
-        {icon({ focused, color, size: theme.iconSize })}
+        {iconWithBadge(color, theme.iconSize)}
         {showLabel ? (
           <Animated.Text
             entering={FadeIn.duration(150)}
+            exiting={FadeOut.duration(120)}
             numberOfLines={1}
             style={[styles.label, { color, fontSize: theme.fontSize }]}
           >
@@ -96,7 +350,7 @@ export const MagicTabItem = forwardRef<RNView, MagicTabItemProps>(
       </AnimatedPressable>
     );
   }
-);
+));
 
 const styles = StyleSheet.create({
   pressable: {
@@ -120,4 +374,69 @@ const styles = StyleSheet.create({
     fontWeight: '600',
     flexShrink: 1,
   },
+  // Material Design 3 bottom layout: icon (with capsule indicator) stacked
+  // over an always-below label.
+  itemBottom: {
+    alignSelf: 'center',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 2,
+    paddingVertical: 3,
+    paddingHorizontal: 4,
+  },
+  indicatorWrap: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  // Compact "light" mode: small icon-only tap target with its own tight padding.
+  itemLight: {
+    alignSelf: 'center',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingVertical: 6,
+    paddingHorizontal: 14,
+  },
+  labelBottom: {
+    fontWeight: '600',
+    textAlign: 'center',
+  },
+  action: {
+    alignSelf: 'center',
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginTop: -22,
+    shadowColor: '#000',
+    shadowOpacity: 0.3,
+    shadowRadius: 8,
+    shadowOffset: { width: 0, height: 4 },
+    elevation: 8,
+  },
+  disabled: {
+    opacity: 0.4,
+  },
+  badge: {
+    position: 'absolute',
+    top: -5,
+    left: '65%',
+    minWidth: 16,
+    height: 16,
+    paddingHorizontal: 4,
+    borderRadius: 8,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  badgeDot: {
+    top: -2,
+    minWidth: 8,
+    width: 8,
+    height: 8,
+    paddingHorizontal: 0,
+    borderRadius: 4,
+  },
+  badgeText: {
+    fontSize: 10,
+    fontWeight: '700',
+    textAlign: 'center',
+  },
 });

package/src/MagicTabs.tsx

@@ -1,20 +1,131 @@
-import type { ReactNode } from 'react';
+import { useMemo, type ReactNode } from 'react';
 import { Tabs, TabList, TabSlot, TabTrigger } from 'expo-router/ui';
+import { usePathname } from 'expo-router';
 import { MagicTabBar } from './MagicTabBar';
 import { MagicTabItem } from './MagicTabItem';
-import { defaultTabs } from './defaultTabs';
 import { defaultTheme } from './theme';
-import type { MagicTabBarTheme, MagicTabBarVariant, MagicTabConfig } from './types';
+import type { Href } from 'expo-router';
+import type {
+  MagicLabelMode,
+  MagicLabelPosition,
+  MagicTabBarTheme,
+  MagicTabBarVariant,
+  MagicTabConfig,
+  MagicTabPressHandler,
+} from './types';
+
+declare const __DEV__: boolean;
+
+/** Best-effort string path for an `Href` (covers string and `{ pathname }` forms). */
+function hrefToPath(href: Href): string {
+  if (typeof href === 'string') return href;
+  const pathname = (href as { pathname?: string })?.pathname;
+  return typeof pathname === 'string' ? pathname : '';
+}
+
+/**
+ * Removes Expo Router group segments (`(group)`) from a path so hrefs match
+ * `usePathname()`. Groups are organizational and never appear in the URL, so
+ * `href: "/(home)/expenses"` must compare against a pathname of `/expenses`.
+ * Collapses any doubled or trailing slashes and falls back to `/` for root.
+ */
+function stripGroupSegments(path: string): string {
+  return (
+    path
+      .replace(/\/\([^/)]+\)/g, '')
+      .replace(/\/{2,}/g, '/')
+      .replace(/(.)\/$/, '$1') || '/'
+  );
+}
+
+/**
+ * Finds the tab whose `href` best matches the current path, by longest prefix
+ * so nested routes (e.g. `/explore/details`) still resolve to their tab.
+ */
+function findActiveTab(
+  tabs: MagicTabConfig[],
+  pathname: string,
+): MagicTabConfig | undefined {
+  let best: MagicTabConfig | undefined;
+  let bestLen = -1;
+  const currentPath = stripGroupSegments(pathname);
+  for (const tab of tabs) {
+    const rawPath = hrefToPath(tab.href);
+    if (!rawPath) continue;
+    const path = stripGroupSegments(rawPath);
+    const matches =
+      path === '/'
+        ? currentPath === '/'
+        : currentPath === path || currentPath.startsWith(`${path}/`);
+    if (matches && path.length > bestLen) {
+      best = tab;
+      bestLen = path.length;
+    }
+  }
+  return best;
+}
+
+/**
+ * Normalizes the `showLabels` prop (boolean shorthand or explicit mode) and
+ * clamps it to what the current `labelPosition` can display well.
+ *
+ * `'always'` only works with `labelPosition="bottom"`: side-by-side, every tab
+ * would expand to its full label width and overflow the bar, so we downgrade
+ * it to `'active'` (and warn in dev).
+ */
+function resolveLabelMode(
+  showLabels: boolean | MagicLabelMode,
+  labelPosition: MagicLabelPosition,
+): MagicLabelMode {
+  const mode: MagicLabelMode =
+    showLabels === true ? 'active' : showLabels === false ? 'never' : showLabels;
+
+  if (mode === 'always' && labelPosition !== 'bottom') {
+    if (__DEV__) {
+      console.warn(
+        '[MagicTabs] showLabels="always" requires labelPosition="bottom"; ' +
+          'falling back to "active". Set labelPosition="bottom" to keep every label visible.',
+      );
+    }
+    return 'active';
+  }
+  return mode;
+}
 
 export interface MagicTabsProps {
   /**
    * The tabs to render, in order. Each entry maps a route to an icon + label.
-   * When omitted, a default set is used — Home, Explore, Notifications, Inbox
-   * and Profile — with matching Ionicons (see {@link defaultTabs}).
+   *
+   * Bring your own icons. For a ready-made demo set, import it explicitly:
+   * `import { defaultTabs } from 'react-native-magic-tab-bar/default-tabs'`.
    */
-  tabs?: MagicTabConfig[];
+  tabs: MagicTabConfig[];
   /** Override any part of the default theme. */
   theme?: Partial<MagicTabBarTheme>;
+  /**
+   * When to show tab labels:
+   * - `true` / `'active'` — only on the focused tab (default).
+   * - `'always'` — on every tab, all the time.
+   * - `false` / `'never'` — icon-only bar.
+   *
+   * A tab without a `label` never shows text. Individual tabs can override
+   * this via their `showLabel` config field.
+   */
+  showLabels?: boolean | MagicLabelMode;
+  /** Place labels to the right of icons (default) or below them. */
+  labelPosition?: MagicLabelPosition;
+  /**
+   * Compact "light" mode. Off by default. When `true`, the bar is shorter,
+   * shows small icons only (labels hidden), and floats with extra bottom
+   * margin. Uses its own dedicated styles.
+   */
+  isLight?: boolean;
+  /**
+   * Extra space between the bar and the bottom edge, in "light" mode only.
+   * Added on top of the safe-area inset. Ignored unless `isLight` is `true`.
+   * Defaults to 14.
+   */
+  lightBottomMargin?: number;
   /** Position the bar floating over content (default) or docked in-flow. */
   variant?: MagicTabBarVariant;
   /**
@@ -36,6 +147,18 @@ export interface MagicTabsProps {
   glass?: boolean;
   /** Render a custom background (e.g. a blur/glass view) behind the bar. */
   renderBackground?: () => ReactNode;
+  /**
+   * Fire a selection haptic when a tab is pressed. Requires the optional
+   * `expo-haptics` package; without it this prop has no effect. Off by default.
+   */
+  haptics?: boolean;
+  /**
+   * Called when any tab is pressed, with the tab's `name` and whether it was
+   * already focused — handy for "scroll to top" / "reset stack" on re-press.
+   */
+  onTabPress?: MagicTabPressHandler;
+  /** Called when any tab is long-pressed. */
+  onTabLongPress?: MagicTabPressHandler;
 }
 
 /**
@@ -53,15 +176,34 @@ export interface MagicTabsProps {
  * ```
  */
 export function MagicTabs({
-  tabs = defaultTabs,
+  tabs,
   theme: themeOverride,
+  showLabels = true,
+  labelPosition = 'right',
+  isLight = false,
+  lightBottomMargin,
   variant,
   isTransparent,
   transparency,
   glass,
   renderBackground,
+  haptics,
+  onTabPress,
+  onTabLongPress,
 }: MagicTabsProps) {
-  const theme: MagicTabBarTheme = { ...defaultTheme, ...themeOverride };
+  // Stable identity so it doesn't re-trigger memoized children every render.
+  const theme = useMemo<MagicTabBarTheme>(
+    () => ({ ...defaultTheme, ...themeOverride }),
+    [themeOverride],
+  );
+  const barLabelMode = resolveLabelMode(showLabels, labelPosition);
+
+  // The bar is "light" when either the whole bar is forced light (`isLight`)
+  // or the currently active tab opts in via its own `isLight` config. Changing
+  // routes flips this and the bar animates between the two layouts.
+  const pathname = usePathname();
+  const activeTab = findActiveTab(tabs, pathname);
+  const effectiveLight = isLight || !!activeTab?.isLight;
 
   return (
     <Tabs>
@@ -70,16 +212,46 @@ export function MagicTabs({
         <MagicTabBar
           theme={theme}
           variant={variant}
+          labelPosition={labelPosition}
+          isLight={effectiveLight}
+          lightBottomMargin={lightBottomMargin}
           isTransparent={isTransparent}
           transparency={transparency}
           glass={glass}
           renderBackground={renderBackground}
         >
-          {tabs.map((tab) => (
-            <TabTrigger key={tab.name} name={tab.name} href={tab.href} asChild>
-              <MagicTabItem icon={tab.icon} label={tab.label} theme={theme} />
-            </TabTrigger>
-          ))}
+          {tabs.map((tab) => {
+            // A tab's `showLabel` overrides the bar-level mode: `false` forces
+            // icon-only, `true` shows it (falling back to `'active'` when the
+            // bar itself is set to `'never'`).
+            const labelMode: MagicLabelMode =
+              tab.showLabel === undefined
+                ? barLabelMode
+                : tab.showLabel
+                  ? barLabelMode === 'never'
+                    ? 'active'
+                    : barLabelMode
+                  : 'never';
+            return (
+              <TabTrigger key={tab.name} name={tab.name} href={tab.href} asChild>
+                <MagicTabItem
+                  name={tab.name}
+                  icon={tab.icon}
+                  label={tab.label}
+                  labelMode={labelMode}
+                  labelPosition={labelPosition}
+                  badge={tab.badge}
+                  disabled={tab.disabled}
+                  variant={tab.variant}
+                  isLight={effectiveLight}
+                  haptics={haptics}
+                  onTabPress={onTabPress}
+                  onTabLongPress={onTabLongPress}
+                  theme={theme}
+                />
+              </TabTrigger>
+            );
+          })}
         </MagicTabBar>
       </TabList>
     </Tabs>

package/src/defaultTabs.tsx

@@ -15,11 +15,12 @@ const ionicon =
   );
 
 /**
- * The tabs used when `<MagicTabs />` is rendered without a `tabs` prop:
- * Home, Explore, Notifications, Inbox and Profile, each with a matching Ionicon.
+ * A ready-made demo tab set — Home, Explore, Notifications, Inbox and Profile,
+ * each with a matching Ionicon. Opt in via the subpath:
+ * `import { defaultTabs } from 'react-native-magic-tab-bar/default-tabs'`.
  *
- * Assumes the app has routes named `index` (`/`), `explore`, `notifications`,
- * `inbox` and `profile`. Pass your own `tabs` to `<MagicTabs />` to override.
+ * Requires `@expo/vector-icons` and assumes the app has routes named `index`
+ * (`/`), `explore`, `notifications`, `inbox` and `profile`.
  */
 export const defaultTabs: MagicTabConfig[] = [
   {