Other exports

Let's take a quick look through some of the useful other exports in @tamagui/core.

Constants

Constants are re-exported from @tamagui/constants :

• isWeb - True if targeting the web. Will be true both for SSR and client.
• isWindowDefined - typeof window !== 'undefined'
• isServer - isWeb && !isWindowDefined.
• isClient - isWeb && isWindowDefined.
• useIsomorphicLayoutEffect - isServer ? useEffect : useLayoutEffect. Helper for SSR rendering without warnings.
• isChrome - client-side Chrome
• isWebTouchable - web-only touch-device (client side only)
• isTouchable - True for any touch device (client side only).

Helpers

The exported getConfig will return your fully parsed Tamagui config. This is safer than importing it directly as it avoids circular imports. In general you want to use useTheme to access themes, and getTokens/getToken/getTokenValue for tokens, but for other parts of the config this can be useful.

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

Will add a new font after initial createTamagui call. Where GenericFont is the same as a font passed to createTamagui, and ParsedFont is the font with the subkeys prefixed with $ and turned into variable objects.

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

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

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

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

;() => TokensParsed

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

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

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

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

;(props: Object) => Object

Take props, returns new object with all shorthand props expanded.

themeable<Comp extends ReactComponentLike>(component: Comp): Comp

A higher order component  that accepts theme and themeInverse, rendering them onto Theme before rendering your component.

type getVariable = (value: Variable) => string

If given a Variable - which comes from a parsed theme or token returned from createTamagui, useTheme or getTokens (read more on the useTheme docs).

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

Hooks

Pass in props that include media styles and shorthands, get back a flat object of props with the current media styles merged and shorthands expanded. This is an advanced pattern that should be used sparingly, as it will trigger updates on every media query used in the props object. Helpful for more complex components that need to pass down props they are given to children (a common example being the size prop, if it's controlling children that also accept size).

// if props is:
//   { size: '$2', $sm: { size: '$4' } }
// and $sm is active, activeProps will be:
//   { size: '$4' }

// if shorthands like m => margin, then m always expands to margin
function MyButton(props) {
  const activeProps = useProps(props)
}

You can pass an option to disable the shorthands expansion, and another option to resolve any token strings into their respective theme or token value:

function MyButton(props) {
  const activeProps = useProps(props)
}

useProps takes a second argument, which is the same as useStyle, documented in the next section.

Pass in props that include media styles and shorthands, get back a flat style object with the current media styles merged, shorthands expanded, and all theme/token values resolved (into CSS variables on the web or values on native by default). This will remove any non-style values and will by default expand all variants and resolve all values.

// if props is:
//   { color: '$background', $sm: { color: '$color' } }
// and $sm is active, activeProps will be on web:
//   { color: 'var(--color)' }
// and on native will resolve to the actual theme or token value:
//   { color: '#fff' }
// this resolve behavior can be controlled, see the docs just below.

// if shorthands like m => margin, then m expands to margin

function MyButton(props) {
  const style = useStyle(props)
}

It can take a couple options to control how it resolves values and handles shorthands:

function MyButton(props) {
  const style = useStyle(props, {
    // option to disable the shorthand expansion
    disableExpandShorthands: true,
    // option to change how values are resolved
    // 'auto' (default) resolves to optimized value on all platforms (CSS variable on web, DynamicColor on iOS, not optimized on android)
    // 'value' resolves to the raw theme/token string on all platforms (the same as useTheme()[name].val)
    resolveValues: 'value',
    // pass a Tamagui component to resolve any custom variants:
    forComponent: CustomComponent
  })
}

Similar to the above two hooks, this returns your fully resolved/merged/media query flattened styles, but instead of returning just props or just style, it returns both of them split out, as well as returning the result of useTheme() and useMedia() that it uses internally:

function MyButton(props) {
  const [props, style, theme, media] = usePropsAndStyle(props, opts)
  // see useStyle to for documentation on opts
  // we return theme, media as they are used internally already in the hook
}

Returns the string name of the current theme.

SSR-friendly, only true on 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.

Type Helpers

Fetches the type of props for a Tamagui component:

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

const X = styled(Stack, {})

type XProps = GetProps<typeof X>

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

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

const X = styled(Stack, {})

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