Incomplete Guide for using xstyled.custom.ts for creating custom xstyled utils

[paramsinghvc]

💬 Questions and Help

Hi,
I'm using xstyled for my project and keen on using some utils like centerAlign, clearFix etc to be used as props on x elements as
<x.div centerAlign clearfix ....

I'm using it in a TS project and following this guide https://xstyled.dev/docs/adding-new-utilities/
and https://xstyled.dev/docs/typescript/
It says to create the xstyled.config.js but what to do with it I'm not sure. I created it in the project root but it doesn't seem to work. Also, TS is not able to identify the custom prop of centerAlign added. The TS guide only talks about custom theme types.

Below is my xstyled.cutom.js looks like.

import { createCss, system, compose, style } from '@xstyled/styled-components';

export const clearfix = style({
  prop: 'clearfix',
  css: () => ({
    '&::after': {
      display: 'block',
      content: '',
      clear: 'both',
    },
  }),
});

export const foo = style({
  prop: ['foo'],
  css: ['paddingTop', 'paddingBottom'],
})

export const { css, styled, x, createGlobalStyle } = createCss(compose(system, clearfix, foo));

So, a complete guide or a sandbox would be great.
Here's a sandbox https://codesandbox.io/p/sandbox/xstyled-v2-playground-forked-q7dy59

[paramsinghvc]

@gregberge

[quantizor]

Thanks for the detailed report and the sandbox, both made the gap easy to see. You're right that the /docs/adding-new-utilities/ page stops short of the parts that matter most: where to import the resulting x and styled from after createCss (your local xstyled.config.ts exports, not @xstyled/styled-components), and the TypeScript story so clearfix is recognized as a prop on <x.div>.

The page lives at website/pages/docs/core-concepts/adding-new-utilities.mdx. A PR that adds two short sections to the end of that file would be very welcome:

• "Use your custom utilities": importing x, styled, css, createGlobalStyle from ./xstyled.config instead of @xstyled/styled-components.
• "TypeScript": the module-augmentation / type-export pattern so custom props type-check on x.*.

Happy to review if you (or anyone reading) wants to take a swing.