From 14f35aaa0394da58d1e016e8fc740cca9ea02a38 Mon Sep 17 00:00:00 2001
From: Michael James <mjames@canva.com>
Date: Tue, 9 Jun 2026 10:48:20 +0800
Subject: [PATCH] Add TypeScript types for sx prop

---
 packages/@stylexjs/stylex/src/stylex.js       |  2 ++
 .../stylex/src/types/StyleXTypes.d.ts         | 14 ++++++++++
 .../@stylexjs/stylex/src/types/StyleXTypes.js |  4 +++
 packages/typescript-tests/src/test1.tsx       | 26 +++++++++++++++++--
 4 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/packages/@stylexjs/stylex/src/stylex.js b/packages/@stylexjs/stylex/src/stylex.js
index e7a505c43..7f47a33f3 100644
--- a/packages/@stylexjs/stylex/src/stylex.js
+++ b/packages/@stylexjs/stylex/src/stylex.js
@@ -26,6 +26,7 @@ import type {
   StyleX$DefineConsts,
   StyleXArray,
   StyleXClassNameFor,
+  StyleXSxProp,
   StyleXStyles,
   StyleXStylesWithout,
   StyleXVar,
@@ -51,6 +52,7 @@ export type {
   StaticStylesWithout,
   StyleXArray,
   StyleXClassNameFor,
+  StyleXSxProp,
   StyleXStyles,
   StyleXStylesWithout,
   StyleXVar,
diff --git a/packages/@stylexjs/stylex/src/types/StyleXTypes.d.ts b/packages/@stylexjs/stylex/src/types/StyleXTypes.d.ts
index b3c938e5f..e2e3d4fdc 100644
--- a/packages/@stylexjs/stylex/src/types/StyleXTypes.d.ts
+++ b/packages/@stylexjs/stylex/src/types/StyleXTypes.d.ts
@@ -235,6 +235,20 @@ export type StyleXStylesWithout<CSS extends UserAuthoredStyles> = StyleXStyles<
   Omit<CSSPropertiesWithExtras, keyof CSS>
 >;
 
+export type StyleXSxProp = StyleXArray<
+  | null
+  | undefined
+  | boolean
+  | CompiledStyles
+  | Readonly<[CompiledStyles, InlineStyles]>
+>;
+
+declare module 'react' {
+  interface DOMAttributes<T> {
+    sx?: StyleXSxProp;
+  }
+}
+
 declare const StyleXVarGroupTag: unique symbol;
 export type VarGroup<
   Tokens extends { [key: string]: any },
diff --git a/packages/@stylexjs/stylex/src/types/StyleXTypes.js b/packages/@stylexjs/stylex/src/types/StyleXTypes.js
index 1ca31746e..f20ea354d 100644
--- a/packages/@stylexjs/stylex/src/types/StyleXTypes.js
+++ b/packages/@stylexjs/stylex/src/types/StyleXTypes.js
@@ -195,6 +195,10 @@ export type StyleXStylesWithout<
   out CSS extends { readonly [string]: unknown },
 > = StyleXStyles<Omit<CSSPropertiesWithExtras, keyof CSS>>;
 
+export type StyleXSxProp = StyleXArray<
+  ?CompiledStyles | boolean | Readonly<[CompiledStyles, InlineStyles]>,
+>;
+
 export type VarGroup<
   out Tokens extends { readonly [string]: unknown },
   out _ID extends string = string,
diff --git a/packages/typescript-tests/src/test1.tsx b/packages/typescript-tests/src/test1.tsx
index bfa83784b..195332f62 100644
--- a/packages/typescript-tests/src/test1.tsx
+++ b/packages/typescript-tests/src/test1.tsx
@@ -7,11 +7,11 @@
  *
  */
 
-/* eslint-disable no-unused-vars */
+/* eslint-disable no-unused-vars, react/no-unknown-property */
 
 import * as React from 'react';
 import * as stylex from '@stylexjs/stylex';
-import type { StaticStyles } from '@stylexjs/stylex';
+import type { StaticStyles, StyleXSxProp } from '@stylexjs/stylex';
 
 type Props = {
   xstyle?: StaticStyles;
@@ -21,6 +21,10 @@ function Component({ xstyle }: Props) {
   return <div {...stylex.props(xstyle)} />;
 }
 
+function PlainComponent() {
+  return null;
+}
+
 const styles = stylex.create({
   base: {
     color: 'red',
@@ -34,3 +38,21 @@ function OtherComponent() {
 function OtherComponent2() {
   return <Component xstyle={[styles.base, undefined]} />;
 }
+
+function SxComponent() {
+  return <div sx={styles.base} />;
+}
+
+function SxComponentMultiStyle() {
+  return <div sx={[styles.base, undefined]} />;
+}
+
+function InvalidSxValue() {
+  // @ts-expect-error - `sx` only accepts StyleX styles.
+  return <div sx="not-stylex" />;
+}
+
+function CustomComponentSx() {
+  // @ts-expect-error - `sx` is only transformed on lowercase JSX host elements.
+  return <PlainComponent sx={styles.base} />;
+}