Other exports

Helpful functions and constants

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).

wwwwwwwwwwwwwwwwwww

Helpers

insertFont

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.

updateFont

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

isTamaguiComponent

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.

isTamaguiElement

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.

getTokens

;() => 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.

getToken

(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

getTokenValue

(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

getExpandedShorthands

;(props: Object) => Object

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

themeable

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

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

getVariable

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.

wwwwwwwwwwwwwwwwwww

Hooks

useProps

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, {
    disableExpandShorthands: true,
    // 'value' resolves to the actual theme/token value on all platforms
    // 'auto' resolves to CSS variable on web, value on native
    // 'variable' resolves to CSS variable on all platforms
    // defaults to not resolving token/theme values so they stay the same as they are input
    resolveValues: 'value'
  })
}

useStyle

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 automatically.

// 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, {
    disableExpandShorthands: true,
    // 'value' resolves to the actual theme/token value on all platforms
    // 'auto' (default) resolves to CSS variable on web, value on native
    // 'variable' resolves to CSS variable on all platforms
    // default is 'auto'
    resolveValues: 'value',
    // pass a Tamagui component with custom variants and it will handle them using this option:
    forComponent: CustomComponent
  })
}

usePropsAndStyle

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 useProps and useStyle to see opts and how these values are resolved
  // theme and media are returned as they are used internally already in the hook
}

Type Helpers

GetProps

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>

GetRef

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} />
}

FontLanguage

Background

Edit this page on GitHub.