@tamagui/web 2.0.0-1768586279389 → 2.0.0-1768696252732

package/src/createComponent.tsx

@@ -1,7 +1,6 @@
 import { composeRefs } from '@tamagui/compose-refs'
 import {
   IS_REACT_19,
-  isAndroid,
   isClient,
   isServer,
   isWeb,
@@ -19,6 +18,7 @@ import { defaultComponentStateMounted } from './defaultComponentState'
 import { getSplitStyles, useSplitStyles } from './helpers/getSplitStyles'
 import { log } from './helpers/log'
 import { type GenericProps, mergeComponentProps } from './helpers/mergeProps'
+import { mergeRenderElementProps } from './helpers/mergeRenderElementProps'
 import { objectIdentityKey } from './helpers/objectIdentityKey'
 import { setElementProps } from './helpers/setElementProps'
 import { subscribeToContextGroup } from './helpers/subscribeToContextGroup'
@@ -415,7 +415,23 @@ export function createComponent<
     }
 
     const groupContextParent = React.useContext(GroupContext)
-    const animationDriver = componentContext.animationDriver
+
+    // Get animation driver - either from animatedBy prop lookup or context
+    const animationDriver = (() => {
+      if (props.animatedBy && config?.animations) {
+        const animations = config.animations
+        // If animations is an object with named drivers (has 'default' key)
+        if ('default' in animations) {
+          return (
+            (animations as Record<string, any>)[props.animatedBy] ?? animations.default
+          )
+        }
+        // Single driver config - only 'default' makes sense
+        return props.animatedBy === 'default' ? animations : null
+      }
+      return componentContext.animationDriver
+    })()
+
     const useAnimations = animationDriver?.useAnimations as UseAnimationHook | undefined
 
     const componentState = useComponentState(
@@ -498,7 +514,7 @@ export function createComponent<
       }
     }, [stateRef, groupName, groupContextParent])
 
-    // if our animation driver supports noReRender, we'll replace this below with
+    // if our animation driver supports avoidReRenders, we'll replace this below with
     // a version that essentially uses an internall emitter rather than setting state
     // but still stores the current state and applies if it it needs to during render
     let setStateShallow = componentState.setStateShallow
@@ -506,9 +522,9 @@ export function createComponent<
     if (process.env.NODE_ENV === 'development' && time) time`use-state`
 
     const isTaggable = !Component || typeof Component === 'string'
-    const tagProp = props.tag
-    // default to tag, fallback to component (when both strings)
-    const element = isWeb ? (isTaggable ? tagProp || Component : Component) : Component
+    const renderProp = props.render
+    // default to render prop, fallback to component (when both strings)
+    const element = isWeb ? (isTaggable ? renderProp || Component : Component) : Component
 
     const BaseTextComponent = BaseText || element || 'span'
     const BaseViewComponent = BaseView || element || (hasTextAncestor ? 'span' : 'div')
@@ -627,7 +643,7 @@ export function createComponent<
 
     if (process.env.NODE_ENV === 'development' && time) time`theme`
 
-    elementType = Component || elementType
+    elementType = element || elementType
     const isStringElement = typeof elementType === 'string'
 
     const mediaState = useMedia(componentContext, debugProp)
@@ -919,8 +935,8 @@ export function createComponent<
       }
     }
 
-    if (tagProp && elementType['acceptTagProp']) {
-      viewProps.tag = tagProp
+    if (renderProp && elementType['acceptTagProp']) {
+      viewProps.render = renderProp
     }
 
     // once you set animation prop don't remove it, you can set to undefined/false
@@ -950,6 +966,7 @@ export function createComponent<
         componentState: state,
         styleProps,
         theme,
+        themeName,
         pseudos: pseudos || null,
         staticConfig,
         stateRef,
@@ -1068,37 +1085,45 @@ export function createComponent<
       })
     }
 
-    // TODO should this be regular effect to allow the render in-between?
+    // Animation enter state machine: true -> 'should-enter' -> false
+    // Stage 1: Set 'should-enter' synchronously before paint to apply enterStyle classes
+    // Stage 2: After browser paint, set false to trigger CSS transition
+    //
+    // CRITICAL: useEffect does NOT guarantee post-paint execution!
+    // See: https://thoughtspile.github.io/2021/11/15/unintentional-layout-effect/
+    // When layoutEffect updates state → re-render before paint → useEffect flushes pre-paint
+    // Solution: Double RAF ensures browser has actually painted before we transition
     useIsomorphicLayoutEffect(() => {
-      // Note: We removed the early return on disabled to allow animations to work
-      // This fixes the issue where animations wouldn't work on disabled components
       if (state.unmounted === true && hasEnterStyle) {
         setStateShallow({ unmounted: 'should-enter' })
         return
       }
 
-      let tm: NodeJS.Timeout
       if (state.unmounted) {
-        if (animationDriver?.supportsCSS || isAndroid) {
-          // this setTimeout fixes css driver enter animations  - not sure why
-          // this setTimeout fixes the conflict when with the safe area view in android
-          tm = setTimeout(() => {
-            setStateShallow({ unmounted: false })
+        // For CSS transitions, we need browser to paint enterStyle before removing it.
+        // Double RAF guarantees paint: first RAF schedules after current frame,
+        // second RAF schedules after that frame completes (including paint).
+        if (supportsCSS) {
+          let cancelled = false
+          requestAnimationFrame(() => {
+            if (cancelled) return
+            requestAnimationFrame(() => {
+              if (cancelled) return
+              setStateShallow({ unmounted: false })
+            })
           })
-          return () => clearTimeout(tm)
-          // don't clearTimeout! safari gets bugs it just doesn't ever set unmounted: false
+          return () => {
+            cancelled = true
+          }
         }
-
+        // Non-CSS drivers handle their own animation timing
         setStateShallow({ unmounted: false })
-        return
       }
 
-      // Only subscribe to context group if not disabled
-
       return () => {
         componentSetStates.delete(setState)
       }
-    }, [state.unmounted, disabled])
+    }, [state.unmounted, supportsCSS])
 
     useIsomorphicLayoutEffect(() => {
       if (disabled) return
@@ -1377,11 +1402,28 @@ export function createComponent<
     if (useChildrenResult) {
       content = useChildrenResult
     } else {
-      content = React.createElement(elementType, viewProps, content)
+      // Handle render prop variants: function, JSX element, or string
+      if (typeof renderProp === 'function') {
+        // Render function: full control with props and state
+        const renderProps = { ...viewProps, children: content }
+        content = renderProp(renderProps, state)
+      } else if (
+        renderProp &&
+        typeof renderProp === 'object' &&
+        React.isValidElement(renderProp)
+      ) {
+        // JSX element: clone with merged props
+        const elementProps = (renderProp as React.ReactElement).props || {}
+        const mergedProps = mergeRenderElementProps(elementProps, viewProps, content)
+        content = React.cloneElement(renderProp as React.ReactElement, mergedProps)
+      } else {
+        content = React.createElement(elementType, viewProps, content)
+      }
     }
 
     // needs to reset the presence state for nested children
-    const ResetPresence = config?.animations?.ResetPresence
+    // Use the resolved animationDriver (handles multi-driver config)
+    const ResetPresence = animationDriver?.ResetPresence
     const needsReset = Boolean(
       // not when passing down to child
       !asChild &&
@@ -1463,10 +1505,6 @@ export function createComponent<
         }
       }
 
-      if (debugProp) {
-        console.info('overriddenContextProps', overriddenContextProps)
-      }
-
       content = (
         <Provider __disableMergeDefaultValues {...overriddenContextProps}>
           {content}

package/src/createTamagui.ts

@@ -166,9 +166,9 @@ export function createTamagui<Conf extends CreateTamaguiProps>(
         }
       }
 
-      const sep = configIn.settings?.cssStyleSeparator || ''
+      const sep = ` `
       function declarationsToRuleSet(decs: string[], selector = '') {
-        return `:root${selector} {${sep}${[...decs].join(`;${sep}`)}${sep}}`
+        return `:root${selector} {${sep}${[...decs].join(`;${sep}`)}\n}`
       }
 
       // non-font

package/src/helpers/getSplitStyles.tsx

@@ -37,6 +37,7 @@ import type {
   GetStyleState,
   PseudoStyles,
   RulesToInsert,
+  SpaceTokens,
   SplitStyleProps,
   StaticConfig,
   StyleObject,
@@ -203,6 +204,7 @@ export const getSplitStyles: StyleSplitter = (
     process.env.TAMAGUI_TARGET === 'native' ? (undefined as any) : {}
   const classNames: ClassNamesObject = {}
 
+  let space: SpaceTokens | null = props.space
   let pseudos: PseudoStyles | null = null
   let hasMedia: boolean | Set<string> = false
   let dynamicThemeAccess: boolean | undefined
@@ -923,10 +925,10 @@ export const getSplitStyles: StyleSplitter = (
                   dynamicThemeAccess = true
                   // only apply if this is the current theme
                   if (isCurrentScheme) {
-                    // update mediastyle so the later merge loop uses correct value
+                    // update mediaStyle so the later merge loop uses correct value
                     mediaStyle[subKey] = val
                   } else {
-                    // Remove from mediaStyle so it doesn't get merged with wrong theme's value
+                    // remove from mediaStyle so it doesn't get merged with wrong theme's value
                     delete mediaStyle[subKey]
                   }
                   continue
@@ -1599,9 +1601,14 @@ const animatableDefaults = {
   ),
   opacity: 1,
   scale: 1,
+  scaleX: 1,
+  scaleY: 1,
   rotate: '0deg',
-  rotateY: '0deg',
   rotateX: '0deg',
+  rotateY: '0deg',
+  rotateZ: '0deg',
+  skewX: '0deg',
+  skewY: '0deg',
   x: 0,
   y: 0,
   borderRadius: 0,

package/src/helpers/getThemeCSSRules.ts

@@ -36,8 +36,6 @@ export function getThemeCSSRules(props: {
     const CNP = `.${THEME_CLASSNAME_PREFIX}`
     let vars = ''
 
-    // themeToVariableToValueMap.set(theme, {})
-    // const varToValMap = themeToVariableToValueMap.get(theme)
     for (const themeKey in theme) {
       const variable = theme[themeKey] as Variable
       let value: any = null
@@ -60,9 +58,9 @@ export function getThemeCSSRules(props: {
     const selectorsSet = new Set(isDarkBase || isLightBase ? baseSelectors : [])
 
     // since we dont specify dark/light in classnames we have to do an awkward specificity war
-    // use config.maxDarkLightNesting to determine how deep you can nest until it breaks
+    // hardcoded to support 2 levels of nesting (e.g. light > dark or dark > light)
     if (hasDarkLight) {
-      const maxDepth = getSetting('maxDarkLightNesting') ?? 3
+      const maxDepth = 2
 
       for (const subName of names) {
         const isDark = isDarkBase || subName.startsWith('dark_')
@@ -83,7 +81,6 @@ export function getThemeCSSRules(props: {
         for (let depth = 0; depth < numSelectors; depth++) {
           const isOdd = depth % 2 === 1
 
-          // wtf is this continue:
           if (isOdd && depth < 3) {
             continue
           }
@@ -106,9 +103,6 @@ export function getThemeCSSRules(props: {
           // for light/dark/light:
           const parentSelectorString = parentSelectors.join(' ')
           selectorsSet.add(`${parentSelectorString} ${nextChildSelector}`)
-          // selectorsSet.add(
-          //   `${parentSelectors.join(' ')} ${nextChildSelector}.is_inversed`.trim()
-          // )
         }
       }
     }
@@ -116,7 +110,6 @@ export function getThemeCSSRules(props: {
     const selectors = [...selectorsSet].sort(sortString)
 
     // only do our :root attach if it's not light/dark - not support sub themes on root saves a lot of effort/size
-    // this isBaseTheme logic could probably be done more efficiently above
     const selectorsString =
       selectors
         .map((x) => {

package/src/helpers/mergeRenderElementProps.ts

@@ -0,0 +1,17 @@
+import { mergeSlotStyleProps } from './mergeSlotStyleProps'
+
+/**
+ * Merges props from a render element with viewProps from Tamagui.
+ * viewProps takes precedence, elementProps provides fallbacks.
+ * Style/className are merged, refs and event handlers are composed.
+ */
+export function mergeRenderElementProps(
+  elementProps: Record<string, any>,
+  viewProps: Record<string, any>,
+  children: any
+): Record<string, any> {
+  // elementProps as base, viewProps as overlay (viewProps wins)
+  const merged = mergeSlotStyleProps({ ...elementProps }, viewProps)
+  merged.children = children
+  return merged
+}

package/src/helpers/mergeSlotStyleProps.ts

@@ -0,0 +1,46 @@
+import { composeRefs } from '@tamagui/compose-refs'
+import { composeEventHandlers } from '@tamagui/helpers'
+
+const isEventHandler = /^on[A-Z]/
+
+/**
+ * Merges props with special handling for style, className, ref, and event handlers.
+ * Used by Slot and render prop implementations.
+ *
+ * @param base - Base props (typically from parent/slot)
+ * @param overlay - Props to merge on top (typically from child/element)
+ * @returns Merged props object (mutates and returns base for perf)
+ */
+export function mergeSlotStyleProps(
+  base: Record<string, any>,
+  overlay: Record<string, any>
+): Record<string, any> {
+  for (const key in overlay) {
+    const baseVal = base[key]
+    const overlayVal = overlay[key]
+
+    if (overlayVal === undefined) continue
+
+    if (key === 'style') {
+      base.style =
+        baseVal && overlayVal ? { ...baseVal, ...overlayVal } : overlayVal || baseVal
+    } else if (key === 'className') {
+      base.className =
+        baseVal && overlayVal ? `${baseVal} ${overlayVal}` : overlayVal || baseVal
+    } else if (key === 'ref') {
+      base.ref =
+        baseVal && overlayVal ? composeRefs(baseVal, overlayVal) : overlayVal || baseVal
+    } else if (
+      isEventHandler.test(key) &&
+      typeof baseVal === 'function' &&
+      typeof overlayVal === 'function'
+    ) {
+      base[key] = composeEventHandlers(baseVal, overlayVal)
+    } else {
+      // overlay wins for regular props
+      base[key] = overlayVal
+    }
+  }
+
+  return base
+}

package/src/helpers/skipProps.ts

@@ -13,7 +13,7 @@ export const skipProps = {
   debug: 1,
   componentName: 1,
   disableOptimization: 1,
-  tag: 1,
+  render: 1,
   style: 1, // handled after loop so pseudos set usedKeys and override it if necessary
   group: 1,
   animatePresence: 1,

package/src/helpers/useRenderElement.tsx

@@ -0,0 +1,66 @@
+import type React from 'react'
+import { cloneElement, createElement, isValidElement } from 'react'
+import { composeRefs } from '@tamagui/compose-refs'
+import type { TamaguiComponentState } from '../types'
+import { mergeSlotStyleProps } from './mergeSlotStyleProps'
+
+export type RenderProp<Props = Record<string, any>> =
+  | string
+  | React.ReactElement
+  | ((props: Props, state: TamaguiComponentState) => React.ReactElement)
+
+/**
+ * Evaluates a render prop and returns the element to render.
+ *
+ * @param render - The render prop (tag string, JSX element, or function)
+ * @param props - Props to pass to the rendered element (including ref)
+ * @param state - Component state for render functions
+ * @param defaultElement - Fallback element if render prop is not provided
+ */
+export function evaluateRenderProp(
+  render: RenderProp | undefined,
+  props: Record<string, any>,
+  state: TamaguiComponentState,
+  defaultElement: React.ReactElement<any>
+): React.ReactElement {
+  if (!render) {
+    return defaultElement
+  }
+
+  const defaultChildren = defaultElement.props.children
+
+  // String tag - swap element type, reuse props from defaultElement
+  if (typeof render === 'string') {
+    return createElement(render, props, defaultChildren)
+  }
+
+  // Render function - call with props and state
+  if (typeof render === 'function') {
+    return render(props, state)
+  }
+
+  // JSX element - clone with merged props
+  if (isValidElement(render)) {
+    const renderProps = render.props as Record<string, any>
+    const renderRef = renderProps?.ref
+
+    // Fast path: no props to merge
+    if (!renderProps || Object.keys(renderProps).length === 0) {
+      if (renderRef) {
+        return cloneElement(
+          render,
+          { ...props, ref: composeRefs(props.ref, renderRef) } as any,
+          defaultChildren
+        )
+      }
+      return cloneElement(render, props as any, defaultChildren)
+    }
+
+    // Merge props (component props as base, render props as overlay)
+    const merged = mergeSlotStyleProps({ ...props }, renderProps)
+    const children = renderProps.children ?? defaultChildren
+    return cloneElement(render, merged as any, children)
+  }
+
+  return defaultElement
+}

package/src/hooks/getThemeProxied.ts

@@ -112,12 +112,13 @@ export function getThemeProxied(
 
           if (process.env.TAMAGUI_TARGET === 'native') {
             // ios can avoid re-rendering in some cases when we are using a root light/dark
-            // disabled in cases where we have animations
+            // disabled in cases where we have animations or when scheme changes from parent (isInverse)
             const shouldOptimize =
               scheme &&
               platform !== 'web' &&
               isIos &&
               !curProps.deopt &&
+              !curState.isInverse &&
               getSetting('fastSchemeChange') &&
               doesRootSchemeMatchSystem()
 

package/src/index.ts

@@ -56,6 +56,7 @@ export {
   getToken,
   getTokens,
   getTokenValue,
+  loadAnimationDriver,
   setConfig,
   setupDev,
   updateConfig,

package/src/interfaces/TamaguiComponentPropsBaseBase.tsx

@@ -1,4 +1,10 @@
-import type { DebugProp, ThemeName, GroupNames, Role } from '../types'
+import type {
+  DebugProp,
+  ThemeName,
+  GroupNames,
+  Role,
+  TamaguiComponentState,
+} from '../types'
 
 export type TamaguiComponentPropsBaseBase = {
   target?: string
@@ -41,10 +47,19 @@ export type TamaguiComponentPropsBaseBase = {
   id?: string
 
   /**
-   * Controls the output tag on web
-   * {@see https://developer.mozilla.org/en-US/docs/Web/HTML/Element}
+   * Controls the rendered element on web.
+   * - String: renders as that HTML element (e.g., `render="button"`)
+   * - JSX Element: clones element with merged props (e.g., `render={<a href="/" />}`)
+   * - Function: full control with props and state (e.g., `render={(props) => <Custom {...props} />}`)
    */
-  tag?: keyof HTMLElementTagNameMap | (string & {})
+  render?:
+    | keyof HTMLElementTagNameMap
+    | (string & {})
+    | React.ReactElement
+    | ((
+        props: Record<string, any> & { ref?: React.Ref<any> },
+        state: TamaguiComponentState
+      ) => React.ReactElement)
 
   /**
    * Applies a theme to this element

package/src/styled.tsx

@@ -46,6 +46,7 @@ export function styled<
     variants?: Variants | undefined
     defaultVariants?: GetVariantAcceptedValues<Variants>
     context?: StyledContext
+    render?: string
   },
   config?: StyledConfig
 ) {
@@ -289,13 +290,13 @@ export function styled<
 // })
 
 // const Test2 = styled(Text1, {
-//   tag: 'p',
+//   render: 'p',
 //   userSelect: 'auto',
 //   color: '$color',
 // })
 
 // const Test3 = styled(Test2, {
-//   tag: 'p',
+//   render: 'p',
 //   userSelect: 'auto',
 //   color: '$color',
 
@@ -307,7 +308,7 @@ export function styled<
 // })
 
 // const Test = styled(Paragraph, {
-//   tag: 'p',
+//   render: 'p',
 //   userSelect: 'auto',
 //   color: '$color',