Skip to content

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

TypeScript

feat(core): add className/style props alongside xstyle (23 components) (#514)

Cindy Zhang55821b4e4efe
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index c60007f377..3f62e79c5c 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -145,9 +145,26 @@ export interface XDSAppShellProps {
topNav?: ReactNode;
/**
- * StyleX overrides for the root element.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
}
// =============================================================================
@@ -293,6 +310,8 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
sideNavWidth = DEFAULT_SIDENAV_WIDTH,
topNav,
xstyle,
+ className,
+ style,
},
ref,
) {
@@ -491,6 +510,8 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
isFill ? styles.rootFill : styles.rootAuto,
xstyle,
),
+ className,
+ style,
)}>
{/* Skip-to-content link */}
<a
diff --git a/packages/core/src/AspectRatio/XDSAspectRatio.tsx b/packages/core/src/AspectRatio/XDSAspectRatio.tsx
index 449af5fe31..9bffe6bb2d 100644
--- a/packages/core/src/AspectRatio/XDSAspectRatio.tsx
+++ b/packages/core/src/AspectRatio/XDSAspectRatio.tsx
@@ -17,10 +17,7 @@ import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {xdsClassName, mergeProps} from '../utils';
-export interface XDSAspectRatioProps extends Omit<
- HTMLAttributes<HTMLElement>,
- 'style' | 'className'
-> {
+export interface XDSAspectRatioProps extends HTMLAttributes<HTMLElement> {
/**
* The aspect ratio as width/height (e.g., 16/9 = 1.777..., 4/3 = 1.333..., 1 for square).
*/
@@ -33,9 +30,26 @@ export interface XDSAspectRatioProps extends Omit<
children: ReactNode;
/**
- * StyleX styles to apply to the aspect ratio container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
}
const styles = stylex.create({
@@ -67,15 +81,19 @@ const styles = stylex.create({
* ```
*/
export const XDSAspectRatio = forwardRef<HTMLElement, XDSAspectRatioProps>(
- function XDSAspectRatio({ratio, children, xstyle, ...props}, ref) {
+ function XDSAspectRatio(
+ {ratio, children, xstyle, className, style, ...props},
+ ref,
+ ) {
return (
<div
ref={ref as React.Ref<HTMLDivElement>}
{...mergeProps(
xdsClassName('aspect-ratio'),
stylex.props(styles.container, xstyle),
+ className,
+ {...style, aspectRatio: ratio},
)}
- style={{aspectRatio: ratio}}
{...props}>
<div {...stylex.props(styles.child)}>{children}</div>
</div>
diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsx
index f1279c70f2..12707accb2 100644
--- a/packages/core/src/Banner/XDSBanner.tsx
+++ b/packages/core/src/Banner/XDSBanner.tsx
@@ -118,9 +118,26 @@ export interface XDSBannerProps {
*/
children?: ReactNode;
/**
- * StyleX override styles applied to the root element.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for the root element.
*/
@@ -338,6 +355,8 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
defaultIsExpanded = false,
children,
xstyle,
+ className,
+ style,
'data-testid': testId,
},
ref,
@@ -382,6 +401,8 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
variant === 'section' && styles.section,
xstyle,
),
+ className,
+ style,
)}>
{/* Header: colored status background */}
<div
diff --git a/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx b/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx
index d244dadc96..23145368c5 100644
--- a/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx
+++ b/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx
@@ -79,9 +79,26 @@ export interface XDSBreadcrumbsProps {
*/
variant?: XDSBreadcrumbsVariant;
/**
- * StyleX styles to apply to the nav container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Accessible label for the nav landmark.
* @default 'Breadcrumb'
@@ -158,6 +175,8 @@ export const XDSBreadcrumbs = forwardRef<HTMLElement, XDSBreadcrumbsProps>(
separator = '/',
variant = 'default',
xstyle,
+ className,
+ style,
label = 'Breadcrumb',
'data-testid': testId,
},
@@ -216,6 +235,8 @@ export const XDSBreadcrumbs = forwardRef<HTMLElement, XDSBreadcrumbsProps>(
{...mergeProps(
xdsClassName('breadcrumbs', {variant}),
stylex.props(navStyles.root, xstyle),
+ className,
+ style,
)}>
<ol {...stylex.props(listStyles.root)}>{rendered}</ol>
</nav>
diff --git a/packages/core/src/Center/XDSCenter.tsx b/packages/core/src/Center/XDSCenter.tsx
index c312caf1ab..7e080ef268 100644
--- a/packages/core/src/Center/XDSCenter.tsx
+++ b/packages/core/src/Center/XDSCenter.tsx
@@ -43,10 +43,7 @@ const dynamicStyles = stylex.create({
export type CenterAxis = 'both' | 'horizontal' | 'vertical';
-export interface XDSCenterProps extends Omit<
- HTMLAttributes<HTMLDivElement>,
- 'style' | 'className'
-> {
+export interface XDSCenterProps extends HTMLAttributes<HTMLDivElement> {
/**
* Center axis - which direction(s) to center.
* - `both`: Center both horizontally and vertically (default)
@@ -80,9 +77,26 @@ export interface XDSCenterProps extends Omit<
children: ReactNode;
/**
- * StyleX styles to apply to the container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
}
/**
@@ -107,6 +121,8 @@ export const XDSCenter = forwardRef<HTMLDivElement, XDSCenterProps>(
isInline = false,
children,
xstyle,
+ className,
+ style,
...props
},
ref,
@@ -121,6 +137,8 @@ export const XDSCenter = forwardRef<HTMLDivElement, XDSCenterProps>(
dynamicStyles.sizing(width ?? null, height ?? null),
xstyle,
),
+ className,
+ style,
);
return (
diff --git a/packages/core/src/Divider/XDSDivider.tsx b/packages/core/src/Divider/XDSDivider.tsx
index dffad704df..691eee1272 100644
--- a/packages/core/src/Divider/XDSDivider.tsx
+++ b/packages/core/src/Divider/XDSDivider.tsx
@@ -25,7 +25,7 @@ import {xdsClassName, mergeProps} from '../utils';
export interface XDSDividerProps extends Omit<
HTMLAttributes<HTMLElement>,
- 'style' | 'className' | 'children'
+ 'children'
> {
/**
* Orientation of the divider.
@@ -55,9 +55,26 @@ export interface XDSDividerProps extends Omit<
isFullBleed?: boolean;
/**
- * StyleX styles to apply to the divider container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
}
const baseStyles = stylex.create({
@@ -137,6 +154,8 @@ export const XDSDivider = forwardRef<HTMLElement, XDSDividerProps>(
variant = 'subtle',
isFullBleed = false,
xstyle,
+ className,
+ style,
...props
},
ref,
@@ -158,6 +177,8 @@ export const XDSDivider = forwardRef<HTMLElement, XDSDividerProps>(
: fullBleedStyles.vertical),
xstyle,
),
+ className,
+ style,
)}
{...props}>
<div
diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
index a3cdcae8cf..25af255e58 100644
--- a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
+++ b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
@@ -57,9 +57,26 @@ export interface XDSDropdownMenuItemProps {
children?: ReactNode;
/**
- * StyleX styles for the root container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
}
/**
@@ -89,12 +106,16 @@ export function XDSDropdownMenuItem({
description,
children,
xstyle,
+ className,
+ style,
}: XDSDropdownMenuItemProps) {
return (
<span
{...mergeProps(
xdsClassName('dropdown-menu-item'),
stylex.props(styles.root, xstyle),
+ className,
+ style,
)}>
{icon && <XDSIcon icon={icon} size="sm" color="secondary" />}
<span {...stylex.props(styles.content)}>
diff --git a/packages/core/src/EmptyState/XDSEmptyState.tsx b/packages/core/src/EmptyState/XDSEmptyState.tsx
index 71b291bb07..1f86f7cdae 100644
--- a/packages/core/src/EmptyState/XDSEmptyState.tsx
+++ b/packages/core/src/EmptyState/XDSEmptyState.tsx
@@ -104,9 +104,26 @@ export interface XDSEmptyStateProps {
*/
isCompact?: boolean;
/**
- * StyleX override styles applied to the container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for the container element.
*/
@@ -137,7 +154,17 @@ export interface XDSEmptyStateProps {
*/
export const XDSEmptyState = forwardRef<HTMLDivElement, XDSEmptyStateProps>(
(
- {title, description, icon, actions, isCompact = false, xstyle, ...props},
+ {
+ title,
+ description,
+ icon,
+ actions,
+ isCompact = false,
+ xstyle,
+ className,
+ style,
+ ...props
+ },
ref,
) => {
return (
@@ -151,6 +178,8 @@ export const XDSEmptyState = forwardRef<HTMLDivElement, XDSEmptyStateProps>(
isCompact && styles.containerCompact,
xstyle,
),
+ className,
+ style,
)}
{...props}>
{icon != null && <div aria-hidden="true">{icon}</div>}
diff --git a/packages/core/src/Field/XDSField.tsx b/packages/core/src/Field/XDSField.tsx
index f4b6964b77..d5503abdf3 100644
--- a/packages/core/src/Field/XDSField.tsx
+++ b/packages/core/src/Field/XDSField.tsx
@@ -15,6 +15,7 @@
import {forwardRef, type HTMLAttributes, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
import {XDSFieldLabel} from './XDSFieldLabel';
import {XDSFieldStatus} from './XDSFieldStatus';
import {
@@ -149,6 +150,27 @@ export interface XDSFieldProps extends Omit<
* @default 'attached'
*/
statusVariant?: 'attached' | 'detached';
+ /**
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
+ */
+ xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* The input or control to render inside the field.
*/
@@ -181,7 +203,10 @@ export const XDSField = forwardRef<HTMLDivElement, XDSFieldProps>(
status,
labelTooltip,
statusVariant = 'attached',
+ xstyle,
children,
+ className,
+ style,
...props
},
ref,
@@ -189,7 +214,12 @@ export const XDSField = forwardRef<HTMLDivElement, XDSFieldProps>(
return (
<div
ref={ref}
- {...mergeProps(xdsClassName('field'), stylex.props(styles.container))}
+ {...mergeProps(
+ xdsClassName('field'),
+ stylex.props(styles.container, xstyle),
+ className,
+ style,
+ )}
{...props}>
<XDSFieldLabel
label={label}
diff --git a/packages/core/src/FormLayout/XDSFormLayout.tsx b/packages/core/src/FormLayout/XDSFormLayout.tsx
index a37c193ae1..fd771fd4dc 100644
--- a/packages/core/src/FormLayout/XDSFormLayout.tsx
+++ b/packages/core/src/FormLayout/XDSFormLayout.tsx
@@ -60,10 +60,7 @@ const styles = stylex.create({
// Props
// =============================================================================
-export interface XDSFormLayoutProps extends Omit<
- HTMLAttributes<HTMLDivElement>,
- 'style' | 'className'
-> {
+export interface XDSFormLayoutProps extends HTMLAttributes<HTMLDivElement> {
/**
* Form fields to arrange. Accepts XDS inputs (XDSTextInput, XDSSelector, etc.)
* and XDSField-wrapped custom controls.
@@ -84,9 +81,26 @@ export interface XDSFormLayoutProps extends Omit<
direction?: XDSFormLayoutDirection;
/**
- * StyleX styles to apply to the layout container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for the root element.
@@ -118,7 +132,7 @@ export interface XDSFormLayoutProps extends Omit<
*/
export const XDSFormLayout = forwardRef<HTMLDivElement, XDSFormLayoutProps>(
function XDSFormLayout(
- {children, direction = 'vertical', xstyle, ...props},
+ {children, direction = 'vertical', xstyle, className, style, ...props},
ref,
) {
const contextValue = useMemo(() => ({direction}), [direction]);
@@ -135,6 +149,8 @@ export const XDSFormLayout = forwardRef<HTMLDivElement, XDSFormLayoutProps>(
direction === 'horizontal-labels' && styles.horizontalLabels,
xstyle,
),
+ className,
+ style,
)}
{...props}>
{children}
diff --git a/packages/core/src/Grid/XDSGrid.tsx b/packages/core/src/Grid/XDSGrid.tsx
index 17b5cb97ef..781dcd7f4b 100644
--- a/packages/core/src/Grid/XDSGrid.tsx
+++ b/packages/core/src/Grid/XDSGrid.tsx
@@ -26,10 +26,7 @@ import {xdsClassName, mergeProps} from '../utils';
export type GridAlignment = 'start' | 'center' | 'end' | 'stretch';
-export interface XDSGridProps extends Omit<
- HTMLAttributes<HTMLElement>,
- 'style' | 'className'
-> {
+export interface XDSGridProps extends HTMLAttributes<HTMLElement> {
/**
* Maximum number of columns.
* - When only columns is set: creates fixed equal-width columns
@@ -89,9 +86,26 @@ export interface XDSGridProps extends Omit<
justify?: GridAlignment;
/**
- * StyleX styles to apply to the grid container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Content to render inside the grid.
@@ -337,6 +351,8 @@ export const XDSGrid = forwardRef<HTMLElement, XDSGridProps>(function XDSGrid(
align,
justify,
xstyle,
+ className,
+ style,
children,
...props
},
@@ -393,8 +409,9 @@ export const XDSGrid = forwardRef<HTMLElement, XDSGridProps>(function XDSGrid(
justify != null && justifyStyles[justify],
xstyle,
),
+ className,
+ {...style, ...inlineStyle},
)}
- style={inlineStyle}
{...props}>
{children}
</div>
diff --git a/packages/core/src/Grid/XDSGridSpan.tsx b/packages/core/src/Grid/XDSGridSpan.tsx
index eafb2bbfb7..c000da6192 100644
--- a/packages/core/src/Grid/XDSGridSpan.tsx
+++ b/packages/core/src/Grid/XDSGridSpan.tsx
@@ -15,10 +15,7 @@ import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {xdsClassName, mergeProps} from '../utils';
-export interface XDSGridSpanProps extends Omit<
- HTMLAttributes<HTMLElement>,
- 'style' | 'className'
-> {
+export interface XDSGridSpanProps extends HTMLAttributes<HTMLElement> {
/**
* Number of columns to span, or 'full' to span all columns.
* - Number: `grid-column: span N`
@@ -33,9 +30,26 @@ export interface XDSGridSpanProps extends Omit<
rows?: number;
/**
- * StyleX styles to apply to the grid span element.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Content to render inside the grid span.
@@ -68,7 +82,10 @@ const baseStyles = stylex.create({
* ```
*/
export const XDSGridSpan = forwardRef<HTMLElement, XDSGridSpanProps>(
- function XDSGridSpan({columns, rows, xstyle, children, ...props}, ref) {
+ function XDSGridSpan(
+ {columns, rows, xstyle, className, style, children, ...props},
+ ref,
+ ) {
// Build inline style for grid spanning
const inlineStyle: React.CSSProperties = {
...(columns != null && {
@@ -85,8 +102,9 @@ export const XDSGridSpan = forwardRef<HTMLElement, XDSGridSpanProps>(
{...mergeProps(
xdsClassName('grid-span'),
stylex.props(baseStyles.span, xstyle),
+ className,
+ {...style, ...inlineStyle},
)}
- style={inlineStyle}
{...props}>
{children}
</div>
diff --git a/packages/core/src/Kbd/XDSKbd.tsx b/packages/core/src/Kbd/XDSKbd.tsx
index e2a42fe29e..d222faada6 100644
--- a/packages/core/src/Kbd/XDSKbd.tsx
+++ b/packages/core/src/Kbd/XDSKbd.tsx
@@ -80,9 +80,26 @@ export interface XDSKbdProps {
keys: string;
/**
- * StyleX overrides for the wrapper element.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
}
/**
@@ -96,12 +113,17 @@ export interface XDSKbdProps {
* <XDSKbd keys="mod+k" />
* ```
*/
-export function XDSKbd({keys, xstyle}: XDSKbdProps) {
+export function XDSKbd({keys, xstyle, className, style}: XDSKbdProps) {
const parts = keys.split('+').map(key => key.trim().toLowerCase());
return (
<span
- {...mergeProps(xdsClassName('kbd'), stylex.props(styles.wrapper, xstyle))}
+ {...mergeProps(
+ xdsClassName('kbd'),
+ stylex.props(styles.wrapper, xstyle),
+ className,
+ style,
+ )}
aria-hidden="true">
{parts.map((key, i) => (
<kbd key={i} {...stylex.props(styles.kbd)}>
diff --git a/packages/core/src/Layer/XDSPopover.tsx b/packages/core/src/Layer/XDSPopover.tsx
index 86b600e838..90be7d7b4a 100644
--- a/packages/core/src/Layer/XDSPopover.tsx
+++ b/packages/core/src/Layer/XDSPopover.tsx
@@ -23,6 +23,7 @@ import React, {
type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
+import {xdsClassName, mergeProps} from '../utils';
import type {StyleXStyles} from '@stylexjs/stylex';
import {useXDSPopover} from './useXDSPopover';
import type {LayerAlignment, LayerPlacement} from './useXDSLayer';
@@ -127,9 +128,26 @@ export interface XDSPopoverProps {
label?: string;
/**
- * Optional StyleX overrides for the popover container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for the popover container.
@@ -253,6 +271,8 @@ export function XDSPopover({
width,
label,
xstyle,
+ className,
+ style,
'data-testid': testId,
}: XDSPopoverProps): ReactElement {
const wrapperRef = useRef<HTMLDivElement>(null);
@@ -414,7 +434,12 @@ export function XDSPopover({
{popover.render(
<div
data-testid={testId}
- {...stylex.props(styles.container, styles.contentPadding, xstyle)}>
+ {...mergeProps(
+ xdsClassName('popover'),
+ stylex.props(styles.container, styles.contentPadding, xstyle),
+ className,
+ style,
+ )}>
{content}
</div>,
{
@@ -435,7 +460,12 @@ export function XDSPopover({
{popover.render(
<div
data-testid={testId}
- {...stylex.props(styles.container, styles.contentPadding, xstyle)}>
+ {...mergeProps(
+ xdsClassName('popover'),
+ stylex.props(styles.container, styles.contentPadding, xstyle),
+ className,
+ style,
+ )}>
{content}
</div>,
{
diff --git a/packages/core/src/List/XDSList.tsx b/packages/core/src/List/XDSList.tsx
index 0ba3b52091..866d8a5ddb 100644
--- a/packages/core/src/List/XDSList.tsx
+++ b/packages/core/src/List/XDSList.tsx
@@ -64,9 +64,26 @@ export interface XDSListProps {
listStyle?: XDSListStyle;
/**
- * StyleX styles to apply to the list container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for testing frameworks.
@@ -147,6 +164,8 @@ export const XDSList = forwardRef<
header,
listStyle = 'none',
xstyle,
+ className,
+ style,
'data-testid': testId,
},
ref,
@@ -201,6 +220,8 @@ export const XDSList = forwardRef<
hasMarkers && styles.listWithMarkers,
xstyle,
),
+ className,
+ style,
)}>
{renderedChildren}
</Tag>
diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsx
index 9169304253..dc5e361932 100644
--- a/packages/core/src/List/XDSListItem.tsx
+++ b/packages/core/src/List/XDSListItem.tsx
@@ -83,9 +83,26 @@ export interface XDSListItemProps {
isSelected?: boolean;
/**
- * StyleX styles to apply to the list item.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for testing frameworks.
@@ -279,6 +296,8 @@ export const XDSListItem = forwardRef<HTMLLIElement, XDSListItemProps>(
isDisabled = false,
isSelected = false,
xstyle,
+ className,
+ style,
'data-testid': testId,
},
ref,
@@ -363,6 +382,8 @@ export const XDSListItem = forwardRef<HTMLLIElement, XDSListItemProps>(
isSelected && styles.selected,
xstyle,
),
+ className,
+ style,
)}
onClick={isInteractive ? handleContainerClick : undefined}>
{hasMarkers ? (
diff --git a/packages/core/src/Pagination/XDSPagination.tsx b/packages/core/src/Pagination/XDSPagination.tsx
index 1aa2f727d8..846b210cb4 100644
--- a/packages/core/src/Pagination/XDSPagination.tsx
+++ b/packages/core/src/Pagination/XDSPagination.tsx
@@ -120,8 +120,27 @@ export interface XDSPaginationProps {
// --- Standard XDS ---
/** Test ID for automated testing. */
'data-testid'?: string;
- /** StyleX overrides for the root element. */
+ /**
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
+ */
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
}
// =============================================================================
@@ -316,6 +335,8 @@ export const XDSPagination = forwardRef<HTMLElement, XDSPaginationProps>(
label = 'Pagination',
'data-testid': testId,
xstyle,
+ className,
+ style,
},
ref,
) {
@@ -491,6 +512,8 @@ export const XDSPagination = forwardRef<HTMLElement, XDSPaginationProps>(
{...mergeProps(
xdsClassName('pagination', {variant, size}),
stylex.props(styles.root, xstyle),
+ className,
+ style,
)}>
{pageSizeOptions != null && pageSizeOptions.length > 0 && (
<div {...stylex.props(styles.pageSizeSelector)}>
diff --git a/packages/core/src/ProgressBar/XDSProgressBar.tsx b/packages/core/src/ProgressBar/XDSProgressBar.tsx
index a1411e0a1f..d10d32bfac 100644
--- a/packages/core/src/ProgressBar/XDSProgressBar.tsx
+++ b/packages/core/src/ProgressBar/XDSProgressBar.tsx
@@ -95,9 +95,26 @@ export interface XDSProgressBarProps {
*/
isIndeterminate?: boolean;
/**
- * StyleX styles to apply to the outer container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for testing utilities.
*/
@@ -249,6 +266,8 @@ export const XDSProgressBar = forwardRef<HTMLDivElement, XDSProgressBarProps>(
size = 'md',
isIndeterminate = false,
xstyle,
+ className,
+ style,
'data-testid': dataTestId,
},
ref,
@@ -267,6 +286,8 @@ export const XDSProgressBar = forwardRef<HTMLDivElement, XDSProgressBarProps>(
{...mergeProps(
xdsClassName('progressbar', {variant, size}),
stylex.props(styles.container, xstyle),
+ className,
+ style,
)}
data-testid={dataTestId}>
{/* Label row */}
diff --git a/packages/core/src/RadioList/XDSRadioList.tsx b/packages/core/src/RadioList/XDSRadioList.tsx
index 317c168fb7..50f60d07c2 100644
--- a/packages/core/src/RadioList/XDSRadioList.tsx
+++ b/packages/core/src/RadioList/XDSRadioList.tsx
@@ -112,9 +112,26 @@ export interface XDSRadioListProps {
*/
labelTooltip?: string;
/**
- * Additional styles for the outer container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for the outer container.
*/
@@ -155,6 +172,8 @@ export function XDSRadioList({
status,
labelTooltip,
xstyle,
+ className,
+ style,
'data-testid': dataTestId,
children,
}: XDSRadioListProps) {
@@ -194,7 +213,9 @@ export function XDSRadioList({
}
labelTooltip={labelTooltip}
statusVariant="detached"
- {...stylex.props(xstyle)}>
+ xstyle={xstyle}
+ className={className}
+ style={style}>
<div
role="radiogroup"
aria-label={label}
diff --git a/packages/core/src/Selector/XDSSelectorOption.tsx b/packages/core/src/Selector/XDSSelectorOption.tsx
index ffc340b807..8d081c63e1 100644
--- a/packages/core/src/Selector/XDSSelectorOption.tsx
+++ b/packages/core/src/Selector/XDSSelectorOption.tsx
@@ -51,9 +51,26 @@ export interface XDSSelectorOptionProps {
children?: ReactNode;
/**
- * StyleX styles for the root container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
}
/**
@@ -85,12 +102,16 @@ export function XDSSelectorOption({
description,
children,
xstyle,
+ className,
+ style,
}: XDSSelectorOptionProps) {
return (
<span
{...mergeProps(
xdsClassName('selector-option'),
stylex.props(styles.root, xstyle),
+ className,
+ style,
)}>
{icon && <XDSIcon icon={icon} size="sm" color="secondary" />}
<span {...stylex.props(styles.content)}>
diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsx
index e883e442c1..05c3bc34fa 100644
--- a/packages/core/src/SideNav/XDSSideNav.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.tsx
@@ -80,10 +80,7 @@ const styles = stylex.create({
// Types
// =============================================================================
-export interface XDSSideNavProps extends Omit<
- HTMLAttributes<HTMLElement>,
- 'style' | 'className'
-> {
+export interface XDSSideNavProps extends HTMLAttributes<HTMLElement> {
/**
* Header area — typically XDSSideNavHeader. Sticky at top.
*/
@@ -105,9 +102,26 @@ export interface XDSSideNavProps extends Omit<
*/
footerIcons?: ReactNode;
/**
- * StyleX overrides for the root container.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for the root element.
*/
@@ -146,6 +160,8 @@ export const XDSSideNav = forwardRef<HTMLElement, XDSSideNavProps>(
footer,
footerIcons,
xstyle,
+ className,
+ style,
'data-testid': testId,
...props
},
@@ -163,6 +179,8 @@ export const XDSSideNav = forwardRef<HTMLElement, XDSSideNavProps>(
{...mergeProps(
xdsClassName('side-nav'),
stylex.props(styles.root, xstyle),
+ className,
+ style,
)}
{...props}>
{hasStickyTop && (
diff --git a/packages/core/src/SideNav/XDSSideNavHeader.tsx b/packages/core/src/SideNav/XDSSideNavHeader.tsx
index 971e77430c..96c5aba2d3 100644
--- a/packages/core/src/SideNav/XDSSideNavHeader.tsx
+++ b/packages/core/src/SideNav/XDSSideNavHeader.tsx
@@ -174,9 +174,26 @@ export interface XDSSideNavHeaderProps {
*/
menu?: ReactNode;
/**
- * StyleX overrides.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for the root element.
*/
@@ -259,6 +276,8 @@ export const XDSSideNavHeader = forwardRef<
subtitleHref,
menu,
xstyle,
+ className,
+ style,
'data-testid': testId,
...props
},
@@ -414,6 +433,8 @@ export const XDSSideNavHeader = forwardRef<
{...mergeProps(
xdsClassName('side-nav-header'),
stylex.props(styles.root, xstyle),
+ className,
+ style,
)}>
{icon &&
(titleHref ? (
@@ -452,6 +473,8 @@ export const XDSSideNavHeader = forwardRef<
{...mergeProps(
xdsClassName('side-nav-header'),
stylex.props(styles.root, xstyle),
+ className,
+ style,
)}
{...props}>
{icon &&
diff --git a/packages/core/src/Slider/XDSSlider.tsx b/packages/core/src/Slider/XDSSlider.tsx
index 053255978c..cd4e8ebfea 100644
--- a/packages/core/src/Slider/XDSSlider.tsx
+++ b/packages/core/src/Slider/XDSSlider.tsx
@@ -70,8 +70,27 @@ export interface XDSSliderBaseProps {
valueDisplay?: 'tooltip' | 'text' | 'none';
/** Tick marks at specified positions with optional labels. */
marks?: Array<{value: number; label?: string}>;
- /** Additional styles. */
+ /**
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
+ */
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/** Test ID for the root element. */
'data-testid'?: string;
}
@@ -320,6 +339,8 @@ export const XDSSlider = forwardRef<HTMLDivElement, XDSSliderProps>(
valueDisplay = 'tooltip',
marks,
xstyle,
+ className,
+ style,
'data-testid': testId,
value,
onChange,
@@ -630,7 +651,9 @@ export const XDSSlider = forwardRef<HTMLDivElement, XDSSliderProps>(
}
labelTooltip={labelTooltip}
statusVariant="detached"
- {...stylex.props(xstyle)}>
+ xstyle={xstyle}
+ className={className}
+ style={style}>
<div {...stylex.props(styles.sliderRow)}>
<div
ref={node => {
diff --git a/packages/core/src/Stack/XDSStack.tsx b/packages/core/src/Stack/XDSStack.tsx
index 4ec99fd8db..0e4324bdb3 100644
--- a/packages/core/src/Stack/XDSStack.tsx
+++ b/packages/core/src/Stack/XDSStack.tsx
@@ -42,10 +42,7 @@ import {xdsClassName, mergeProps} from '../utils';
*/
export type StackAlignment = StackMainAlignment | StackCrossAlignment;
-export interface XDSStackProps extends Omit<
- HTMLAttributes<HTMLElement>,
- 'style' | 'className'
-> {
+export interface XDSStackProps extends HTMLAttributes<HTMLElement> {
/**
* Direction of the stack layout.
* - `horizontal`: Items flow left-to-right (like XDSHStack)
@@ -93,9 +90,26 @@ export interface XDSStackProps extends Omit<
element?: ElementType;
/**
- * StyleX styles to apply to the stack.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Content to render inside the stack.
@@ -139,6 +153,8 @@ export const XDSStack = forwardRef<HTMLElement, XDSStackProps>(
wrap,
element = 'div',
xstyle,
+ className,
+ style,
children,
...props
},
@@ -172,6 +188,8 @@ export const XDSStack = forwardRef<HTMLElement, XDSStackProps>(
...mergeProps(
xdsClassName('stack', {direction, gap, wrap}),
stylexProps,
+ className,
+ style,
),
...props,
},
diff --git a/packages/core/src/Stack/XDSStackItem.tsx b/packages/core/src/Stack/XDSStackItem.tsx
index 5ca5a02b19..1f605a42fb 100644
--- a/packages/core/src/Stack/XDSStackItem.tsx
+++ b/packages/core/src/Stack/XDSStackItem.tsx
@@ -27,10 +27,7 @@ import {
} from './stackItem.stylex';
import {xdsClassName, mergeProps} from '../utils';
-export interface XDSStackItemProps extends Omit<
- HTMLAttributes<HTMLElement>,
- 'style' | 'className'
-> {
+export interface XDSStackItemProps extends HTMLAttributes<HTMLElement> {
/**
* Overrides the default cross-alignment for this item.
* (hAlign for VStack, vAlign for HStack)
@@ -53,9 +50,26 @@ export interface XDSStackItemProps extends Omit<
element?: ElementType;
/**
- * StyleX styles to apply to the stack item.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Content to render inside the stack item.
@@ -79,7 +93,16 @@ export interface XDSStackItemProps extends Omit<
*/
export const XDSStackItem = forwardRef<HTMLElement, XDSStackItemProps>(
function XDSStackItem(
- {crossAlignSelf, size, element = 'div', xstyle, children, ...props},
+ {
+ crossAlignSelf,
+ size,
+ element = 'div',
+ xstyle,
+ className,
+ style,
+ children,
+ ...props
+ },
ref,
) {
const stylexProps = stylex.props(
@@ -91,7 +114,12 @@ export const XDSStackItem = forwardRef<HTMLElement, XDSStackItemProps>(
element,
{
ref: ref as Ref<Element>,
- ...mergeProps(xdsClassName('stack-item', {size}), stylexProps),
+ ...mergeProps(
+ xdsClassName('stack-item', {size}),
+ stylexProps,
+ className,
+ style,
+ ),
...props,
},
children,
diff --git a/packages/core/src/StatusDot/XDSStatusDot.tsx b/packages/core/src/StatusDot/XDSStatusDot.tsx
index a502a869b7..6dc7043dc3 100644
--- a/packages/core/src/StatusDot/XDSStatusDot.tsx
+++ b/packages/core/src/StatusDot/XDSStatusDot.tsx
@@ -114,9 +114,26 @@ export interface XDSStatusDotProps {
*/
isPulsing?: boolean;
/**
- * Optional StyleX styles override.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Optional test ID for testing.
*/
@@ -137,7 +154,19 @@ export interface XDSStatusDotProps {
* ```
*/
export const XDSStatusDot = forwardRef<HTMLSpanElement, XDSStatusDotProps>(
- ({variant, size = 'md', label, isPulsing = false, xstyle, ...props}, ref) => {
+ (
+ {
+ variant,
+ size = 'md',
+ label,
+ isPulsing = false,
+ xstyle,
+ className,
+ style,
+ ...props
+ },
+ ref,
+ ) => {
return (
<span
ref={ref}
@@ -153,6 +182,8 @@ export const XDSStatusDot = forwardRef<HTMLSpanElement, XDSStatusDotProps>(
isPulsing && styles.reducedMotion,
xstyle,
),
+ className,
+ style,
)}
{...props}
/>
diff --git a/packages/core/src/Text/XDSHeading.tsx b/packages/core/src/Text/XDSHeading.tsx
index 3f647e53b1..175573dd5e 100644
--- a/packages/core/src/Text/XDSHeading.tsx
+++ b/packages/core/src/Text/XDSHeading.tsx
@@ -141,11 +141,26 @@ export interface XDSHeadingProps {
hasStrikethrough?: boolean;
/**
- * Constrained styles for layout integration.
- * Allows margins, width constraints, flex child props, text alignment.
- * Typography properties (fontSize, fontWeight, color, etc.) should NOT be used.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Heading content
@@ -199,6 +214,8 @@ export const XDSHeading = forwardRef<HTMLHeadingElement, XDSHeadingProps>(
hasCapsize = false,
hasStrikethrough = false,
xstyle,
+ className,
+ style,
children,
...props
},
@@ -278,8 +295,9 @@ export const XDSHeading = forwardRef<HTMLHeadingElement, XDSHeadingProps>(
// User xstyle
xstyle,
),
+ className,
+ {...style, ...inlineStyle},
)}
- style={inlineStyle}
title={tooltipEnabled ? truncation.fullText : undefined}
{...ariaProps}
{...props}>
diff --git a/packages/core/src/Text/XDSText.tsx b/packages/core/src/Text/XDSText.tsx
index cad4f8973b..8753595312 100644
--- a/packages/core/src/Text/XDSText.tsx
+++ b/packages/core/src/Text/XDSText.tsx
@@ -136,11 +136,26 @@ export interface XDSTextProps {
hasTabularNumbers?: boolean;
/**
- * Constrained styles for layout integration.
- * Allows margins, width constraints, flex child props, text alignment.
- * Typography properties (fontSize, fontWeight, color, etc.) should NOT be used.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Text content
@@ -195,6 +210,8 @@ export const XDSText = forwardRef<HTMLElement, XDSTextProps>(function XDSText(
hasStrikethrough = false,
hasTabularNumbers = false,
xstyle,
+ className,
+ style,
as: Component = 'span',
children,
...props
@@ -270,8 +287,9 @@ export const XDSText = forwardRef<HTMLElement, XDSTextProps>(function XDSText(
// User xstyle
xstyle,
),
+ className,
+ {...style, ...inlineStyle},
)}
- style={inlineStyle}
title={tooltipEnabled ? truncation.fullText : undefined}
{...props}>
{children}
diff --git a/packages/core/src/Token/XDSToken.tsx b/packages/core/src/Token/XDSToken.tsx
index d2cfa763a7..44fc124c1f 100644
--- a/packages/core/src/Token/XDSToken.tsx
+++ b/packages/core/src/Token/XDSToken.tsx
@@ -101,9 +101,26 @@ export interface XDSTokenProps {
*/
isLabelHidden?: boolean;
/**
- * Additional StyleX styles to apply to the root element.
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
*/
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/**
* Test ID for testing frameworks.
*/
@@ -314,6 +331,8 @@ export const XDSToken = forwardRef<HTMLElement, XDSTokenProps>(
endContent,
isLabelHidden = false,
xstyle,
+ className,
+ style,
'data-testid': testId,
},
ref,
@@ -365,6 +384,8 @@ export const XDSToken = forwardRef<HTMLElement, XDSTokenProps>(
isDisabled && styles.disabled,
xstyle,
),
+ className,
+ style,
)}>
{content}
</a>
@@ -394,6 +415,8 @@ export const XDSToken = forwardRef<HTMLElement, XDSTokenProps>(
isDisabled && styles.disabled,
xstyle,
),
+ className,
+ style,
)}>
{icon}
<button
@@ -440,6 +463,8 @@ export const XDSToken = forwardRef<HTMLElement, XDSTokenProps>(
isDisabled && styles.disabled,
xstyle,
),
+ className,
+ style,
)}>
{content}
</span>
diff --git a/packages/core/src/Tokenizer/XDSTokenizer.tsx b/packages/core/src/Tokenizer/XDSTokenizer.tsx
index 8f0cde81e6..26b5af56cc 100644
--- a/packages/core/src/Tokenizer/XDSTokenizer.tsx
+++ b/packages/core/src/Tokenizer/XDSTokenizer.tsx
@@ -111,8 +111,27 @@ export interface XDSTokenizerProps<T extends XDSSearchableItem> {
debounceMs?: number;
/** Query change callback. */
onChangeQuery?: (query: string) => void;
- /** StyleX overrides. */
+ /**
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
+ */
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/** Test ID. */
'data-testid'?: string;
}
@@ -250,6 +269,8 @@ export function XDSTokenizer<T extends XDSSearchableItem>({
debounceMs,
onChangeQuery,
xstyle,
+ className,
+ style,
'data-testid': testId,
}: XDSTokenizerProps<T>) {
const inputId = useId();
@@ -395,7 +416,10 @@ export function XDSTokenizer<T extends XDSSearchableItem>({
}
: undefined
}
- labelTooltip={labelTooltip}>
+ labelTooltip={labelTooltip}
+ xstyle={xstyle}
+ className={className}
+ style={style}>
<div
ref={wrapperRef}
role="group"
@@ -411,7 +435,6 @@ export function XDSTokenizer<T extends XDSSearchableItem>({
status && inputStatusBorderStyles[status.type],
status && inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
- xstyle,
)}>
{tokens}
<XDSBaseTypeahead
diff --git a/packages/core/src/Typeahead/XDSTypeahead.tsx b/packages/core/src/Typeahead/XDSTypeahead.tsx
index b57c6fccd4..4592f1136f 100644
--- a/packages/core/src/Typeahead/XDSTypeahead.tsx
+++ b/packages/core/src/Typeahead/XDSTypeahead.tsx
@@ -95,8 +95,27 @@ export interface XDSTypeaheadProps<T extends XDSSearchableItem> {
onChangeQuery?: (query: string) => void;
/** Callback when dropdown opens/closes. */
onOpenChange?: (isOpen: boolean) => void;
- /** StyleX overrides. */
+ /**
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```tsx
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <Component xstyle={overrides.root} />
+ * ```
+ */
xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
/** Test ID. */
'data-testid'?: string;
}
@@ -201,6 +220,8 @@ export function XDSTypeahead<T extends XDSSearchableItem>({
onChangeQuery,
onOpenChange,
xstyle,
+ className,
+ style,
'data-testid': testId,
}: XDSTypeaheadProps<T>) {
const inputId = useId();
@@ -338,7 +359,10 @@ export function XDSTypeahead<T extends XDSSearchableItem>({
}
: undefined
}
- labelTooltip={labelTooltip}>
+ labelTooltip={labelTooltip}
+ xstyle={xstyle}
+ className={className}
+ style={style}>
<div
ref={wrapperRef}
data-testid={testId}
@@ -352,7 +376,6 @@ export function XDSTypeahead<T extends XDSSearchableItem>({
status && inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
isDisabled && inputWrapperStyles.disabled,
- xstyle,
)}>
{showToken && (
<XDSToken
diff --git a/packages/core/src/utils/mergeProps.ts b/packages/core/src/utils/mergeProps.ts
index d84345f686..0622747c7f 100644
--- a/packages/core/src/utils/mergeProps.ts
+++ b/packages/core/src/utils/mergeProps.ts
@@ -1,24 +1,40 @@
/**
- * Merge stylex.props result with an xds-* class name.
+ * Merge xds-* class name, stylex.props result, and optional consumer className/style.
*
* stylex.props() returns { className, style }. This merges the xds-*
* class name into the className string so both StyleX styles and the
* stable theme-targeting class are applied.
*
+ * Consumer className is appended after StyleX classes.
+ * Consumer style is spread after StyleX inline styles, so these values take priority.
+ *
* @example
* ```tsx
* <div {...mergeProps(
* xdsClassName('button', { variant }),
- * stylex.props(styles.base, variants[variant])
+ * stylex.props(styles.base, variants[variant]),
+ * className,
+ * style,
* )} />
* ```
*/
export function mergeProps(
xdsClass: string,
stylexResult: {className?: string; style?: object},
+ className?: string,
+ style?: React.CSSProperties,
): {className: string; style?: object} {
- const merged = stylexResult.className
+ let cls = stylexResult.className
? `${xdsClass} ${stylexResult.className}`
: xdsClass;
- return {className: merged, style: stylexResult.style};
+ if (className) {
+ cls = `${cls} ${className}`;
+ }
+
+ const mergedStyle =
+ style && stylexResult.style
+ ? {...stylexResult.style, ...style}
+ : style || stylexResult.style;
+
+ return {className: cls, style: mergedStyle};
}