Show your utils

[lukemorales]

I think one of the greatest things is the possibility to create theme utils that make our lives easier. How about we use this discussion to showcase and list what the users have created?

utils: {
  // margin
  mt: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      marginTop: formattedValue,
    };
  },
  mr: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      marginRight: formattedValue,
    };
  },
  mb: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      marginBottom: formattedValue,
    };
  },
  ml: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      marginLeft: formattedValue,
    };
  },
  mx: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      marginLeft: formattedValue,
      marginRight: formattedValue,
    };
  },
  my: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      marginTop: formattedValue,
      marginBottom: formattedValue,
    };
  },

  // padding
  pt: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      paddingTop: formattedValue,
    };
  },
  pr: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      paddingRight: formattedValue,
    };
  },
  pb: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      paddingBottom: formattedValue,
    };
  },
  pl: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      paddingLeft: formattedValue,
    };
  },
  px: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      paddingLeft: formattedValue,
      paddingRight: formattedValue,
    };
  },
  py: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      paddingTop: formattedValue,
      paddingBottom: formattedValue,
    };
  },

  // sizes
  w: (value: PropertyValue<'width'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      width: formattedValue,
    };
  },
  h: (value: PropertyValue<'height'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      height: formattedValue,
    };
  },
  minW: (value: PropertyValue<'minWidth'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      minWidth: formattedValue,
    };
  },
  minH: (value: PropertyValue<'minHeight'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      minHeight: formattedValue,
    };
  },
  size: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      height: formattedValue,
      width: formattedValue,
    };
  },
  minSize: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      minHeight: formattedValue,
      minWidth: formattedValue,
    };
  },
  ratio: (value: PropertyValue<'aspectRatio'>) => ({
    aspectRatio: value,
  }),

  // border
  borderX: (value: PropertyValue<'border'>) => ({
    borderLeft: value,
    borderRight: value,
  }),
  borderY: (value: PropertyValue<'border'>) => ({
    borderTop: value,
    borderBottom: value,
  }),
  br: (value: PropertyValue<'borderRadius'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      borderRadius: formattedValue,
    };
  },
  borderTopRadius: (value: PropertyValue<'borderRadius'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      borderTopLeftRadius: formattedValue,
      borderTopRightRadius: formattedValue,
    };
  },
  borderRightRadius: (value: PropertyValue<'borderRadius'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      borderTopRightRadius: formattedValue,
      borderBottomRightRadius: formattedValue,
    };
  },
  borderBottomRadius: (value: PropertyValue<'borderRadius'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      borderBottomLeftRadius: formattedValue,
      borderBottomRightRadius: formattedValue,
    };
  },
  borderLeftRadius: (value: PropertyValue<'borderRadius'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      borderTopLeftRadius: formattedValue,
      borderBottomLeftRadius: formattedValue,
    };
  },

  // background
  bg: (value: ScaleValue<'colors'>) => ({
    background: value,
  }),
  bgColor: (value: ScaleValue<'colors'>) => ({
    backgroundColor: value,
  }),
  bgImage: (value: PropertyValue<'backgroundImage'>) => ({
    backgroundImage: value,
  }),
  bgSize: (value: PropertyValue<'backgroundSize'>) => ({
    backgroundSize: value,
  }),
  bgPosition: (value: PropertyValue<'backgroundPosition'>) => ({
    backgroundPosition: value,
  }),
  bgRepeat: (value: PropertyValue<'backgroundRepeat'>) => ({
    backgroundRepeat: value,
  }),
  linearGradient: (value: PropertyValue<'backgroundImage'>) => ({
    backgroundImage: `linear-gradient(${value})`,
  }),

  // display
  flexDir: (value: PropertyValue<'flexDirection'>) => ({
    backgroundImage: value,
  }),

  // position
  pos: (value: PropertyValue<'position'>) => ({
    position: value,
  }),
  // using inlay to not conflict with existing property inset
  // which does the same thing but is not widely adopted by browsers yet
  inlay: (value: ScaleValue<'space'>) => {
    const formattedValue = formatUtilValue(value);

    return {
      top: formattedValue,
      right: formattedValue,
      bottom: formattedValue,
      left: formattedValue,
    };
  },
},

[soska]

We have a textStyles object that has predefined typography styles from a previous design system that we share with React Native. In order to start using them with stitches, I made a small util that opened a whole world of possibilities:

textStyle: (style: keyof typeof textStyles) => {
  return textStyles[style];
}

So now I can use textStyle as a property in my stitches components with editor autocomplete and all. It feels like magic!

[peduarte]

Woah. This sounds awesome. Do you have a repro I can look at (I'm curious). Cheers

[lukemorales]

Awesome use of utils @soska 🥳!
We will discover a lot of fun things as people collaborate more on this discussion!

[soska]

Do you have a repro I can look at (I'm curious).

Actually I cannot! I tried to reproduce it in codesandbox since our code is private and closed source and it doesn't work. Lol, I don't know why it does work on my app and now I'm nervous.

[lukemorales]

@soska perhaps because in the codesandbox you have a very old version of stitches? It's using 0.0.2

[soska]

You're right! I mindlessly forked the first sandbox I saw with stitches in it. I haven't used codesandbox before.

But it does indeed work.

Thanks a lot for all your work!

[sandgraham]

Sharing a few thoughts...

At work, I decided to prefix all of our utils with _. We have a lot of people contribute to the frontend who aren't super familiar with CSS so I wanted to make sure folks wouldn't be confused by properties they couldn't look up.

Here are our most popular utils:

const stitches = createStitches({
  utils: {
    // Nudge an element by a certain number of pixels
    _nudgeX: (x: number) => ({ transform: `translateX(${ x }px)` }),
    _nudgeY: (y: number) => ({ transform: `translateY(${ y }px)` }),
    _nudge: ([x, y]: [number, number]) => ({ transform: `translate(${ x }px, ${y}px)` }),
    
    // Clamp a line of text to a certain number of rows
    _lineClamp: (value: number) => ({
      display: "-webkit-box",
      WebkitLineClamp: value,
      WebkitBoxOrient: "vertical",
      overflow: "hidden"
    }),

    // Truncate a line of text with an ellipsis
    _truncate: () => ({
      overflow: "hidden",
      textOverflow: "ellipsis",
      whiteSpace: "nowrap"
    })
  }
})

When I first started the project I added a _typography util for quickly applying typographic presets to any element:

const typographicStyles = {
  display: { fontSize: 50, fontFamily: "fantasy" },
  heading: { fontSize: 25, fontFamily: "cursive" }
}
const stitches = createStitches({
  utils: {
    _typography: (style: keyof typeof typographicStyles) => (typographicStyles[style])
  }
})

But eventually I replaced it in favor of a CSSComponent:

const typography = css({
  variants: {
    typeStyle: {
      display: { fontSize: 50, fontFamily: "fantasy" },
      heading: { fontSize: 25, fontFamily: "cursive" }
    }
  }
})

I prefer the latter since it is already used as the basis for a reusable Text component but can also be composed as needed to create other styles- all while preserving an entire typography API (there are other variants like uppercase or color). I think this has led to more consistent styles (and less patterns to worry about for developers).