Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(xstyle): add stylex.create() guidance to 16 component xstyle props (#1952)

Joeyf0775f4fdefb
diff --git a/packages/core/src/Carousel/XDSCarousel.tsx b/packages/core/src/Carousel/XDSCarousel.tsx
index dca67906e6..d444a22ec1 100644
--- a/packages/core/src/Carousel/XDSCarousel.tsx
+++ b/packages/core/src/Carousel/XDSCarousel.tsx
@@ -56,6 +56,16 @@ export interface XDSCarouselProps extends XDSBaseProps<HTMLDivElement> {
*/
'aria-label'?: string;
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSCarousel xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
className?: string;
style?: React.CSSProperties;
diff --git a/packages/core/src/Chat/XDSChatComposerDrawer.tsx b/packages/core/src/Chat/XDSChatComposerDrawer.tsx
index d9ee9d57a7..472372f8f2 100644
--- a/packages/core/src/Chat/XDSChatComposerDrawer.tsx
+++ b/packages/core/src/Chat/XDSChatComposerDrawer.tsx
@@ -59,6 +59,16 @@ export interface XDSChatComposerDrawerProps extends XDSBaseProps<HTMLDivElement>
*/
onCollapsedChange?: (isCollapsed: boolean) => void;
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSChatComposerDrawer xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
className?: string;
style?: React.CSSProperties;
diff --git a/packages/core/src/Chat/XDSChatDictationButton.tsx b/packages/core/src/Chat/XDSChatDictationButton.tsx
index efa44f8740..f83990e6db 100644
--- a/packages/core/src/Chat/XDSChatDictationButton.tsx
+++ b/packages/core/src/Chat/XDSChatDictationButton.tsx
@@ -37,7 +37,16 @@ export interface XDSChatDictationButtonProps {
isHiddenWhenUnsupported?: boolean;
/** Accessible label override. */
label?: string;
- /** Additional StyleX styles. */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSChatDictationButton xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
}
diff --git a/packages/core/src/Chat/XDSChatLayout.tsx b/packages/core/src/Chat/XDSChatLayout.tsx
index d56ea43710..05bb6eab1a 100644
--- a/packages/core/src/Chat/XDSChatLayout.tsx
+++ b/packages/core/src/Chat/XDSChatLayout.tsx
@@ -92,7 +92,16 @@ export interface XDSChatLayoutProps {
*/
scrollRef?: React.RefObject<HTMLElement | null>;
- /** StyleX overrides. */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSChatLayout xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
/** CSS class name(s) appended to the root element. */
className?: string;
diff --git a/packages/core/src/Chat/XDSChatMessage.tsx b/packages/core/src/Chat/XDSChatMessage.tsx
index f8498975ae..51b9fb5880 100644
--- a/packages/core/src/Chat/XDSChatMessage.tsx
+++ b/packages/core/src/Chat/XDSChatMessage.tsx
@@ -54,6 +54,16 @@ export interface XDSChatMessageProps {
*/
metadata?: ReactNode;
density?: XDSChatDensity;
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSChatMessage xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
className?: string;
style?: React.CSSProperties;
diff --git a/packages/core/src/Chat/XDSChatMessageBubble.tsx b/packages/core/src/Chat/XDSChatMessageBubble.tsx
index 5cdccdbc27..9738fc7492 100644
--- a/packages/core/src/Chat/XDSChatMessageBubble.tsx
+++ b/packages/core/src/Chat/XDSChatMessageBubble.tsx
@@ -81,7 +81,16 @@ export interface XDSChatMessageBubbleProps {
*/
group?: 'first' | 'middle' | 'last';
- /** StyleX overrides. */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSChatMessageBubble xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
/** CSS class name(s). */
className?: string;
diff --git a/packages/core/src/Chat/XDSChatMessageList.tsx b/packages/core/src/Chat/XDSChatMessageList.tsx
index e716d83dd8..2c5483fca2 100644
--- a/packages/core/src/Chat/XDSChatMessageList.tsx
+++ b/packages/core/src/Chat/XDSChatMessageList.tsx
@@ -69,7 +69,14 @@ export interface XDSChatMessageListProps {
density?: XDSChatDensity;
/**
- * StyleX overrides.
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSChatMessageList xstyle={styles.wrapper} />
+ * ```
*/
xstyle?: StyleXStyles;
/** CSS class name(s) appended to the root element. */
diff --git a/packages/core/src/Chat/XDSChatSendButton.tsx b/packages/core/src/Chat/XDSChatSendButton.tsx
index 247b4f14da..1c741e95a0 100644
--- a/packages/core/src/Chat/XDSChatSendButton.tsx
+++ b/packages/core/src/Chat/XDSChatSendButton.tsx
@@ -42,7 +42,16 @@ export interface XDSChatSendButtonProps {
stopIcon?: ReactNode;
/** Button size. @default 'md' */
size?: 'sm' | 'md';
- /** Additional StyleX styles. */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSChatSendButton xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
}
diff --git a/packages/core/src/Chat/XDSChatSystemMessage.tsx b/packages/core/src/Chat/XDSChatSystemMessage.tsx
index 93bb23e8e5..53dab11569 100644
--- a/packages/core/src/Chat/XDSChatSystemMessage.tsx
+++ b/packages/core/src/Chat/XDSChatSystemMessage.tsx
@@ -55,7 +55,16 @@ export interface XDSChatSystemMessageProps {
*/
icon?: ReactNode;
- /** StyleX overrides. */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSChatSystemMessage xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
/** CSS class name(s). */
className?: string;
diff --git a/packages/core/src/CodeBlock/XDSCode.tsx b/packages/core/src/CodeBlock/XDSCode.tsx
index f35cd276e8..dc7c81383f 100644
--- a/packages/core/src/CodeBlock/XDSCode.tsx
+++ b/packages/core/src/CodeBlock/XDSCode.tsx
@@ -43,7 +43,16 @@ export interface XDSCodeProps {
ref?: React.Ref<HTMLElement>;
/** Code content */
children: ReactNode;
- /** StyleX override styles */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSCode xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
/** CSS class name(s) */
className?: string;
diff --git a/packages/core/src/CommandPalette/XDSCommandPaletteInput.tsx b/packages/core/src/CommandPalette/XDSCommandPaletteInput.tsx
index 6cca57134b..69b01fe0a8 100644
--- a/packages/core/src/CommandPalette/XDSCommandPaletteInput.tsx
+++ b/packages/core/src/CommandPalette/XDSCommandPaletteInput.tsx
@@ -121,7 +121,16 @@ export interface XDSCommandPaletteInputProps extends Omit<
*/
endContent?: ReactNode;
- /** StyleX styles for the wrapper element. */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSCommandPaletteInput xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
}
diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
index 6a88d6a70f..690df566d0 100644
--- a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
+++ b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
@@ -87,7 +87,16 @@ export interface XDSDropdownMenuItemProps {
isDisabled?: boolean;
/** Additional content to render after the label/description. */
children?: ReactNode;
- /** StyleX styles merged with the component's base styles. */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSDropdownMenuItem xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
/** CSS class name(s) appended to the root element. */
className?: string;
diff --git a/packages/core/src/Markdown/XDSMarkdown.tsx b/packages/core/src/Markdown/XDSMarkdown.tsx
index 1b3b208cb0..b550828a92 100644
--- a/packages/core/src/Markdown/XDSMarkdown.tsx
+++ b/packages/core/src/Markdown/XDSMarkdown.tsx
@@ -138,6 +138,16 @@ export interface XDSMarkdownProps {
* for overlapping ranges.
*/
inlinePlugins?: MarkdownInlinePlugin[];
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSMarkdown xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
className?: string;
style?: React.CSSProperties;
diff --git a/packages/core/src/NavMenu/XDSNavMenuItem.tsx b/packages/core/src/NavMenu/XDSNavMenuItem.tsx
index f8d99d21b1..aba2cb86dd 100644
--- a/packages/core/src/NavMenu/XDSNavMenuItem.tsx
+++ b/packages/core/src/NavMenu/XDSNavMenuItem.tsx
@@ -75,7 +75,16 @@ export interface XDSNavMenuItemProps {
onClick?: () => void;
/** Whether the item is disabled. @default false */
isDisabled?: boolean;
- /** StyleX styles merged with the component's base styles. */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSNavMenuItem xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
/** CSS class name(s) appended to the root element. */
className?: string;
diff --git a/packages/core/src/Overlay/XDSOverlay.tsx b/packages/core/src/Overlay/XDSOverlay.tsx
index ee8058bc56..4604d32742 100644
--- a/packages/core/src/Overlay/XDSOverlay.tsx
+++ b/packages/core/src/Overlay/XDSOverlay.tsx
@@ -44,7 +44,16 @@ export interface XDSOverlayProps {
position?: OverlayPosition;
/** @default "end" */
align?: OverlayAlign;
- /** StyleX style overrides on the container. */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSOverlay xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
/** CSS class name(s) appended to the root element. */
className?: string;
@@ -64,8 +73,7 @@ export interface XDSOverlayProps {
* ```
* <XDSOverlay
* showOn="hover"
- * content={<XDSButton label="Quick view" variant="ghost" />}
- * >
+ * content={<XDSButton label="Quick view" variant="ghost" />}>
* <XDSAspectRatio ratio={16/9}>
* <img src="hero.jpg" style={{objectFit: 'cover', width: '100%', height: '100%'}} />
* </XDSAspectRatio>
diff --git a/packages/core/src/ToggleButton/XDSToggleButtonGroup.tsx b/packages/core/src/ToggleButton/XDSToggleButtonGroup.tsx
index 89a64a5b67..c95626cdcf 100644
--- a/packages/core/src/ToggleButton/XDSToggleButtonGroup.tsx
+++ b/packages/core/src/ToggleButton/XDSToggleButtonGroup.tsx
@@ -103,7 +103,16 @@ interface XDSToggleButtonGroupBaseProps {
*/
isDisabled?: boolean;
- /** StyleX overrides for the group container. */
+ /**
+ * StyleX styles for layout customization (margins, positioning, sizing).
+ * Must be a `stylex.create()` value — not an inline style object.
+ *
+ * @example
+ * ```
+ * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+ * <XDSToggleButtonGroup xstyle={styles.wrapper} />
+ * ```
+ */
xstyle?: StyleXStyles;
/** Test ID for testing frameworks. */