get

The get function extracts values from deeply nested objects using dot notation paths. It’s used internally by Theme UI to resolve theme values and supports the special __default key for nested theme scales.

Function Signature

function get(
  obj: object,
  path: string | number | undefined,
  fallback?: unknown,
  p?: number,
  undef?: unknown
): any

Parameters

object

required

The object to extract values from (typically a theme, variant, or style object).

string | number | undefined

required

Path to the desired value. Can be:

Dot-separated string (e.g., 'colors.primary.light')
Number for array access
undefined returns the fallback

any

Default value returned if the path is not found in the object. If not provided and path is not found, returns undefined.

number

Internal parameter for iteration (not intended for direct use).

unknown

Internal parameter for undefined checks (not intended for direct use).

Returns

any

The value at the specified path. If the value is an object with a __default key, returns the value of that key. Returns the fallback value if the path doesn’t exist.

How It Works

Basic Path Resolution

The function traverses the object using dot notation:

import { get } from '@theme-ui/css'

const theme = {
  colors: {
    primary: '#07c',
    text: '#000'
  },
  space: [0, 4, 8, 16, 32]
}

get(theme, 'colors.primary')  // → '#07c'
get(theme, 'space.2')          // → 8
get(theme, 'space.10', 0)      // → 0 (fallback)

The `__default` Key

When a path resolves to an object containing the special __default key, get returns the value of that key instead of the object itself:

const theme = {
  colors: {
    primary: {
      __default: '#07c',
      light: '#39f',
      dark: '#05a'
    }
  }
}

get(theme, 'colors.primary')        // → '#07c' (from __default)
get(theme, 'colors.primary.light')  // → '#39f'
get(theme, 'colors.primary.dark')   // → '#05a'

Array Access

Arrays can be accessed using numeric indices:

const theme = {
  space: [0, 4, 8, 16, 32, 64],
  fontSizes: [12, 14, 16, 20, 24, 32]
}

get(theme, 'space.0')      // → 0
get(theme, 'space.3')      // → 16
get(theme, 'fontSizes.2')  // → 16

You can also pass the number directly:

get(theme.space, 3)  // → 16
get(theme.space, 10, 0)  // → 0 (fallback, index doesn't exist)

Fallback Values

When a path doesn’t exist, the fallback value is returned:

const theme = {
  colors: {
    primary: '#07c'
  }
}

get(theme, 'colors.secondary', '#639')  // → '#639'
get(theme, 'colors.accent')             // → undefined
get(theme, 'spacing.1', 4)              // → 4

The `THEME_UI_DEFAULT_KEY`

The __default key is exported as a constant:

import { THEME_UI_DEFAULT_KEY } from '@theme-ui/css'

console.log(THEME_UI_DEFAULT_KEY)  // → '__default'

const theme = {
  colors: {
    primary: {
      [THEME_UI_DEFAULT_KEY]: '#07c',
      light: '#39f'
    }
  }
}

Use Cases

Nested Color Scales

Create color palettes with multiple shades:

const theme = {
  colors: {
    blue: {
      __default: '#0066cc',
      50: '#e6f2ff',
      100: '#b3d9ff',
      200: '#80bfff',
      500: '#0066cc',
      900: '#003366'
    }
  }
}

get(theme, 'colors.blue')      // → '#0066cc'
get(theme, 'colors.blue.100')  // → '#b3d9ff'
get(theme, 'colors.blue.900')  // → '#003366'

Typography Scales

const theme = {
  fonts: {
    body: 'system-ui, sans-serif',
    heading: 'Georgia, serif',
    mono: {
      __default: 'Menlo, monospace',
      code: 'Monaco, monospace',
      terminal: 'Courier New, monospace'
    }
  }
}

get(theme, 'fonts.mono')          // → 'Menlo, monospace'
get(theme, 'fonts.mono.code')     // → 'Monaco, monospace'

Safe Property Access

Use get to safely access potentially undefined paths:

const userTheme = {}  // User hasn't defined a theme

// Instead of: userTheme.colors?.primary || '#07c'
const primaryColor = get(userTheme, 'colors.primary', '#07c')

// Instead of: userTheme.space?.[3] || 16
const spacing = get(userTheme, 'space.3', 16)

Variant Extraction

const theme = {
  buttons: {
    primary: {
      color: 'white',
      bg: 'primary',
      padding: 3
    },
    secondary: {
      color: 'text',
      bg: 'secondary',
      padding: 2
    }
  }
}

const primaryButton = get(theme, 'buttons.primary')
// → { color: 'white', bg: 'primary', padding: 3 }

const buttonPadding = get(theme, 'buttons.primary.padding', 2)
// → 3

Examples

Basic Usage

import { get } from '@theme-ui/css'

const theme = {
  colors: {
    primary: '#07c',
    secondary: '#639'
  }
}

const primary = get(theme, 'colors.primary')
const accent = get(theme, 'colors.accent', '#f90')

With Nested Scales

const theme = {
  colors: {
    primary: {
      __default: '#07c',
      light: '#39f',
      dark: '#05a'
    }
  }
}

// Get default value
const primary = get(theme, 'colors.primary')  // '#07c'

// Get nested value
const primaryLight = get(theme, 'colors.primary.light')  // '#39f'

Dynamic Paths

const theme = {
  space: [0, 4, 8, 16, 32]
}

const getSpacing = (scale) => get(theme, `space.${scale}`, 0)

getSpacing(2)   // → 8
getSpacing(10)  // → 0 (fallback)

In Custom Components

import { get } from '@theme-ui/css'
import { useTheme } from '@theme-ui/core'

function CustomButton({ variant = 'primary' }) {
  const theme = useTheme()
  const buttonStyles = get(theme, `buttons.${variant}`, {})
  
  return <button sx={buttonStyles}>Click me</button>
}

Internal Usage

The get function is used internally by the css function for:

Resolving theme values (e.g., color: 'primary' → color: theme.colors.primary)
Accessing scale values by index (e.g., padding: 3 → padding: theme.space[3])
Handling negative values for margins and positioning
Processing variant references

Edge Cases

Numeric String Paths

const arr = [10, 20, 30]

get(arr, '1')   // → 20 (string '1' works for arrays)
get(arr, 1)     // → 20

Undefined Paths

get(theme, undefined, 'default')  // → 'default'
get(theme, '')                     // → theme (empty string returns obj)

Deep Nesting

const theme = {
  components: {
    buttons: {
      variants: {
        primary: {
          states: {
            hover: { bg: 'blue' }
          }
        }
      }
    }
  }
}

get(theme, 'components.buttons.variants.primary.states.hover.bg')
// → 'blue'

css - Main styling function that uses get internally
sx prop - Component styling that relies on theme lookups

Core

Styling

Color Modes

Components

Packages

get

get

Function Signature

Parameters

Returns

How It Works

Basic Path Resolution

The `__default` Key

Array Access

Fallback Values

The `THEME_UI_DEFAULT_KEY`

Use Cases

Nested Color Scales

Typography Scales

Safe Property Access

Variant Extraction

Examples

Basic Usage

With Nested Scales

Dynamic Paths

In Custom Components

Internal Usage

Edge Cases

Numeric String Paths

Undefined Paths

Deep Nesting

​get

​Function Signature

​Parameters

​Returns

​How It Works

​Basic Path Resolution

​The __default Key

​Array Access

​Fallback Values

​The THEME_UI_DEFAULT_KEY

​Use Cases

​Nested Color Scales

​Typography Scales

​Safe Property Access

​Variant Extraction

​Examples

​Basic Usage

​With Nested Scales

​Dynamic Paths

​In Custom Components

​Internal Usage

​Edge Cases

​Numeric String Paths

​Undefined Paths

​Deep Nesting

​Related

get

Function Signature

Parameters

Returns

How It Works

Basic Path Resolution

The `__default` Key

Array Access

Fallback Values

The `THEME_UI_DEFAULT_KEY`

Use Cases

Nested Color Scales

Typography Scales

Safe Property Access

Variant Extraction

Examples

Basic Usage

With Nested Scales

Dynamic Paths

In Custom Components

Internal Usage

Edge Cases

Numeric String Paths

Undefined Paths

Deep Nesting

Related