Exports

Import core utilities from tamagui or @tamagui/core. Ref utilities are also available from @tamagui/element.

Constants

Constants are re-exported from @tamagui/constants:

• isWeb: true if targeting the web (true for SSR and client)
• isBrowser: true when both navigator and location are defined
• isServer: isWeb && !isBrowser
• isClient: isWeb && isBrowser
• isChrome: client-side Chrome
• isWebTouchable: web-only touch device (client side only)
• isTouchable: true on native or touch-capable web clients

Helpers

getConfig returns your fully parsed Tamagui config. It avoids the circular imports that come with importing the config directly. Prefer useTheme for themes and getTokens/getToken/getTokenValue for tokens, and use this for other parts of the config.

type insertFont = (name: string, fontIn: GenericFont) => ParsedFont
Copy

Adds a new font after the initial createTamagui call. GenericFont matches a font passed to createTamagui, and ParsedFont is the font with subkeys turned into variable objects.

The same as insertFont, but will update an existing font.

type isTamaguiComponent = (component: any, name?: string) => boolean
Copy

If no name given, true if a Tamagui component, if name given ensures it’s the specific named Tamagui component.

type isTamaguiElement = (child: any, name?: string) => boolean
Copy

If no name given, true if a Tamagui ReactElement, if name given ensures it’s the specific named Tamagui component element.

;() => TokensParsed
Copy

Returns the parsed Tamagui config object of all your tokens, can be used at runtime to get values from tokens. If you are looking to get a single token value, prefer getToken or getTokenValue.

;(name: Token, group?: keyof Tokens) => any
Copy

Given the specific name of a token or a name + group, will return the value as either a variable on the web, or raw value on native. So if you define a size token with key small and value of 14:

getToken('size.small') // returns on web var(--size-small), native 14
getToken('small', 'size') // returns on web var(--size-small), native 14
Copy

;(name: Token, group?: keyof Tokens) => any
Copy

Similar to getToken, but always returns the raw value rather than the variable name. If you define a size token with key small and value of 14:

getTokenValue('size.small') // returns 14
getTokenValue('small', 'size') // returns 14
Copy

type getVariable = (value: Variable) => string
Copy

Accepts a Variable from a parsed theme or token (returned by createTamagui, useTheme, or getTokens).

Calling getVariable(useTheme().color) returns var(--color) on web, and #fff on other platforms.

splitStyleProps partitions an object in one pass and returns [selectedProps, remainingProps]. With no options, the first object contains style props and the second contains everything else. Props keep their authored keys by default. It is exported from @tamagui/core, @tamagui/ui, and tamagui:

import { splitStyleProps } from 'tamagui'

const [styleProps, regularProps] = splitStyleProps(props)
Copy

Pass expandShorthands: true to write selected shorthand props under their canonical keys:

const [styleProps, regularProps] = splitStyleProps(props, {
  expandShorthands: true,
})
Copy

A filter map selects only its canonical keys. Style props excluded by the map remain in the second object. This also lets a component intentionally select non-style behavior props:

import { splitStyleProps, stylePropsTextOnly } from '@tamagui/core'

const [textProps, frameProps] = splitStyleProps(props, {
  expandShorthands: true,
  filter: {
    ...stylePropsTextOnly,
    ellipsis: true,
    numberOfLines: true,
  },
})
Copy

For dynamic rules, filter can be a callback. It receives the canonical key, the value, the original authored key, and whether the canonical key is a known style prop:

const [selectedProps, remainingProps] = splitStyleProps(props, {
  filter: (key, value, originalKey, isStyleProp) => {
    return (isStyleProp && key.startsWith('font')) || originalKey === 'numberOfLines'
  },
})
Copy

Filter maps infer the selected keys precisely. A callback can return a type predicate on originalKey when its rule narrows to a known key union.

A runtime utility that narrows a TamaguiElement to an HTMLElement. Throws if the element is not an HTMLElement. Useful for platform-specific code where you know you’re on web.

import { getWebElement } from 'tamagui' // or '@tamagui/element'

// Narrows to HTMLElement
const el = getWebElement(ref.current)

// Or narrow to a specific element type
const input = getWebElement<HTMLInputElement>(ref.current)
input.selectionStart // typed correctly
Copy

Hooks

See useMedia for media queries and useTheme for theme values.

Uses useEffect on the server and useLayoutEffect on the client to avoid layout effect warnings during server rendering.

For platform-specific files (.tsx and .native.tsx), this hook creates a properly typed ref for web that also composes with a forwarded ref. When you need to access HTMLElement-specific properties like selectionStart on inputs, this avoids needing any casts.

import { useWebRef } from 'tamagui' // or '@tamagui/element'

// In your .tsx (web) file:
function MyInput(props, forwardedRef) {
  const { ref, composedRef } = useWebRef<HTMLInputElement>(forwardedRef)

  // ref.current is typed as HTMLInputElement
  // Access web-specific properties safely:
  const start = ref.current?.selectionStart

  // composedRef forwards to both ref and forwardedRef
  return <StyledInput ref={composedRef} />
}
Copy

For platform-specific files (.native.tsx), this hook creates a properly typed ref for React Native that also composes with a forwarded ref. Pairs with useWebRef for cross-platform component development.

import { useNativeRef } from 'tamagui' // or '@tamagui/element'

// In your .native.tsx file:
function MyComponent(props, forwardedRef) {
  const { ref, composedRef } = useNativeRef(forwardedRef)

  // ref.current is typed as View
  return <StyledView ref={composedRef} />
}
Copy

For input components, use useNativeInputRef which types to TextInput:

import { useNativeInputRef } from 'tamagui' // or '@tamagui/element'

function MyInput(props, forwardedRef) {
  const { ref, composedRef } = useNativeInputRef(forwardedRef)
  // ref.current is typed as TextInput
  return <StyledInput ref={composedRef} />
}
Copy

Returns the string name of the current theme.

SSR-friendly, only true if native touchable or web touchable device (client side, not server side).

SSR-friendly, returns true if SSR has completed on the client, false before hydration done. On server it’s always false.

Components

A component that opts its children out of SSR. When wrapped in ClientOnly, Tamagui avoids double-renders in various places which results in faster client-side rendering.

import { ClientOnly } from 'tamagui' // or '@tamagui/core'

// Children will render only on the client, skipping SSR entirely
<ClientOnly>
  <MyClientOnlyComponent />
</ClientOnly>

// Can be conditionally enabled
<ClientOnly enabled={shouldSkipSSR}>
  <MyComponent />
</ClientOnly>
Copy

Type helpers

Fetches the type of props for a Tamagui component:

import { View, GetProps, styled } from '@tamagui/core'

const X = styled(View, {})

type XProps = GetProps<typeof X>
Copy

Fetches the type of a ref for a Tamagui component, or any React component:

import { View, GetRef, styled } from '@tamagui/core'

const X = styled(View, {})

const MyComponent = () => {
  const ref = useRef<GetRef<typeof X>>()
  return <X ref={ref} />
}
Copy