API

styled()

With our styled
function, you can easily extend existing components and make them customizable and themeable.

const StyledButton = styled(
  Pressable,
  {
    bg: "$primary600",
    px: "$6",
    py: "$4",
    _dark: {
      bg: "$gray800",
    },
  },
  {}, // componentConfig,
  {} // extendedBaseConfig,
)

componentConfig

Step
1
:
descendantStyle is an array of string that denotes the descendants of that component that should respond to parents state. This is useful for creating complex styles that is dependent on the component that this prop is passed in.
{
descendantStyle: ["_text", "_spinner"]
// ancestorStyle: ['_text'];
// resolveProps: ['placeholderTextColor'];
}
Step
2
:
ancestorStyle is an array of string that denotes the ancestors of that component. This is useful for creating complex styles that are dependent on the ancestor component.
{
// descendantStyle: ['_text', '_spinner'];
ancestorStyle: ["_text"]
// resolveProps: ['placeholderTextColor'];
}
So if this component finds a parent component with
_text
prop, it will apply the styles to the component.
Step
3
:
resolveProps is an array of string that denotes the props that should be resolved. This is useful for props that are not passed into the style property rather goes in as a prop. For example,
placeholderTextColor
in TextInput.
{
// descendantStyle: ['_text', '_spinner'];
// ancestorStyle: ['_text'];
resolveProps: ["placeholderTextColor"]
}
Note: For this to work you also need to add the prop in
propertyTokenMap
, that can be defined in the next parameter of styled function i.e. extendedBaseConfig.

extendedBaseConfig

extendedBaseConfig is an object that let’s you extend the base config for the component. This is useful when you want to define some aliases, tokens, propertyTokenMap, and propertyResolver that is specific to the component.

{
  aliases: {
    pTC: 'placeholderTextColor',
  },
  tokens: {
    placeholderTextColor: 'placeholderTextColor',
  },
  propertyTokenMap: {
    placeholderTextColor: 'colors',
  },
  propertyResolver: {
    placeholderTextColor: (rawValue,resolver)=>{
      return resolver(rawValue)
    },
  },

  <StyledTextInput placeholder="Enter text" pTC="$primary600" />
}

this will merge the following to the base config (gluestack-style.config.js) for the scope of that component.

StyledProvider

gluestack-style Style exports a StyledProvider component that can be used to configure your components. This is useful when you want to define some aliases, tokens, propertyTokenMap, propertyResolver and globalStyle at a global level throughout your app. You can define them in

gluestack-style.config.js

file and pass it to the StyledProvider.

Apart from config StyledProvider also accepts colorMode, which denotes the current active colorMode of the application and globalStyleInjector, which is a function that can be used to inject global styles.

import { StyledProvider, createConfig } from "@gluestack-style/react"

const config = createConfig({
  aliases: {
    bg: "backgroundColor",
    bgColor: "backgroundColor",
    rounded: "borderRadius",
    h: "height",
    w: "width",
  },
  tokens: {
    colors: {
      primary0: "#ffffff",
      primary400: "#c084fc",
      primary500: "#a855f7",
      primary600: "#9333ea",
    },
    space: {
      4: 16,
      5: 20,
      6: 24,
    },
    radii: {
      sm: 4,
      md: 6,
    },
    letterSpacings: {
      md: 0,
    },
    lineHeights: {
      sm: 20,
      md: 22,
    },
    fontWeights: {
      normal: "400",
      medium: "500",
    },
    fontSizes: {
      sm: 14,
      md: 16,
    },
    mediaQueries: {
      sm: "@media (min-width: 480px)",
      md: "@media (min-width: 768px)",
    },
  },
  globalStyle: {
    variants: {
      shadow: {
        softShadow: {
          shadowOffset: {
            width: 0,
            height: 0,
          },
          shadowRadius: 10,
          shadowOpacity: 0.1,
          _android: {
            shadowColor: "$primary500",
            elevation: 5,
            shadowOpacity: 0.05,
          },
        },
      },
    },
  },
} as const)

;<StyledProvider config={config}>
  <App />
</StyledProvider>

propertyResolver

is an object that lets you define a custom resolver for a property or prop. This is useful when you want to define a custom resolver for a property.

{
  propertyResolver: {
    backgroundColor: (rawValue,resolver)=>{
      return hexToRGBA(resolver(rawValue),0.5)
    },
  },
}

in the above example the backgroundColor will be resolved to a rgba value with opacity 0.5.

The resolver function takes two arguments, the first one is the

rawValue

and the second one is the

resolver

function. The resolver function is used to resolve the rawValue to a token value.

Note: The key in

propertyResolver

object should be the same as the key in

propertyTokenMap

i.e. it can only be a

property

not an

alias

mediaQueries

is an object that lets you define a custom media queries(breakpoints) for your app. To configure mediaQueries in

@gluestack-style/react

, you can create a

gluestack-style.config.js

file where you define your mediaQueries and other configuration options.

{
  mediaQueries: {
    base: '@media screen and (min-width: 0)',
    sm: '@media screen and (min-width: 480px)',
    md: '@media screen and (min-width: 768px)',
    lg: '@media screen and (min-width: 992px)',
    xl: '@media screen and (min-width: 1280px)',
  },
}

in your component style config you can write the following to make the component responsive.

{
  "@md": {
    p: '$3',
  },
  "@lg": {
    p: '$4',
  },
}

Platform

If your style demands of some different styling for different platforms, you can write platform specific styles like:

const StyledInput = styled(
  TextInput,
  {
    py: "$2",
    bg: "$gray50",
    borderRadius: "$2",
    _dark: {
      bg: "$gray800",
    },
    _web: {
      px: "$3",
    },
    _ios: {
      px: "$4",
    },
  },
  componentConfig,
  extendedBaseConfig
)

states

If your component has different states than you can write state specific styles like:

const StyledInput = styled(
  TextInput,
  {
    py: "$2",
    bg: "$gray50",
    borderRadius: "$2",
    ":hover": {
      bg: "$gray100",
    },
    ":disabled": {
      bg: "$gray200",
    },
  },
  componentConfig,
  extendedBaseConfig
)

These

states

styles are applied when your state gets

true

, these states are passed in

states

prop of the component.

<StyledInput states={{ hover: true, disabled: true }} />

colorMode

If your component has different colorModes than you can write colorMode specific styles like:

const StyledInput = styled(
  TextInput,
  {
    py: "$2",
    bg: "$gray50",
    borderRadius: "$2",
    _dark: {
      bg: "$gray800",
    },
    _light: {
      bg: "$gray50",
    },
  },
  componentConfig,
  extendedBaseConfig
)

These

colorMode

styles are applied when your style colorMode matches with the active colorMode, the colorMode is passed in

colorMode

prop of the StyledProvider.

<StyledProvider colorMode="dark">
  <App />
</StyledProvider>

sx

prop is a prop that lets you write inline styles for the component.

const StyledInput = styled(
  TextInput,
  {
    py: "$2",
    bg: "$gray50",
    borderRadius: "$2",
  },
  componentConfig,
  extendedBaseConfig
)

;<StyledInput sx={{ py: "$4" }} />

Note:

prop will override the styles defined in the component config. We highly recommend you to use this as little as possible. Mostly when you want to write some layout styles like margin or padding for the component.

Utility Props

gluestack-style Style provides utility props that can be used to style the component. These props get converted to sx prop internally. There is a simple rule, all the utility props are the final property you want to get attached on the style of your component, It will override all other stylings except style prop.

const StyledInput = styled(
  TextInput,
  {
    py: "$2",
    bg: "$gray50",
    borderRadius: "$2",
  },
  componentConfig,
  extendedBaseConfig
)

;<StyledInput py="$4" bg="$gray800" />