Skip to content

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

TypeScript

feat(layout): add padding and isScrollable props to Stack/StackItem (#3342)

Cindy Zhang73940a67ca1d
diff --git a/.changeset/stack-padding-scrollable.md b/.changeset/stack-padding-scrollable.md
new file mode 100644
index 0000000000..e0ad10fb8d
--- /dev/null
+++ b/.changeset/stack-padding-scrollable.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Stack/HStack/VStack: add `padding`, `paddingInline`, `paddingBlock` (spacing-scale inner padding) and `isScrollable` (`overflow: auto`) props; StackItem also gains `isScrollable`. These match the existing `padding`/`isScrollable` props on `Card`, `LayoutContent`, and `LayoutPanel`, so common frame layouts no longer need inline `style={{}}` for padding or the flex scroll-region pattern.
+@cixzhang
diff --git a/apps/storybook/stories/Stack.stories.tsx b/apps/storybook/stories/Stack.stories.tsx
index 61411dbdb3..c42764e448 100644
--- a/apps/storybook/stories/Stack.stories.tsx
+++ b/apps/storybook/stories/Stack.stories.tsx
@@ -133,6 +133,26 @@ const meta: Meta<typeof Stack> = {
options: [0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10],
description: 'Spacing step for gap between items',
},
+ padding: {
+ control: 'select',
+ options: [0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10],
+ description: 'Inner padding on all sides (spacing step)',
+ },
+ paddingInline: {
+ control: 'select',
+ options: [0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10],
+ description:
+ 'Inline (horizontal) padding; overrides padding on that axis',
+ },
+ paddingBlock: {
+ control: 'select',
+ options: [0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10],
+ description: 'Block (vertical) padding; overrides padding on that axis',
+ },
+ isScrollable: {
+ control: 'boolean',
+ description: 'Enables scrollable overflow (overflow: auto)',
+ },
hAlign: {
control: 'select',
options: [
@@ -648,3 +668,56 @@ export const PageLayout: Story = {
</Stack>
),
};
+
+// ============================================================================
+// Padding — inner padding via the spacing scale (no inline styles needed)
+// ============================================================================
+
+export const Padding: Story = {
+ args: {
+ gap: 2,
+ padding: 4,
+ },
+ render: args => (
+ <Stack {...args} xstyle={styles.container}>
+ <Box>Item 1</Box>
+ <Box>Item 2</Box>
+ <Box>Item 3</Box>
+ </Stack>
+ ),
+};
+
+export const PaddingPerAxis: Story = {
+ args: {
+ gap: 2,
+ paddingInline: 6,
+ paddingBlock: 2,
+ },
+ render: args => (
+ <Stack {...args} xstyle={styles.container}>
+ <Box>Item 1</Box>
+ <Box>Item 2</Box>
+ <Box>Item 3</Box>
+ </Stack>
+ ),
+};
+
+// ============================================================================
+// Scrollable — overflow: auto via the isScrollable prop
+// ============================================================================
+
+export const Scrollable: Story = {
+ args: {
+ gap: 2,
+ padding: 2,
+ isScrollable: true,
+ height: 160,
+ },
+ render: args => (
+ <Stack {...args} xstyle={styles.container}>
+ {Array.from({length: 12}, (_, i) => (
+ <Box key={i}>Item {i + 1}</Box>
+ ))}
+ </Stack>
+ ),
+};
diff --git a/packages/core/src/Layout/padding.stylex.ts b/packages/core/src/Layout/padding.stylex.ts
index d911dd2f9a..59e41b8957 100644
--- a/packages/core/src/Layout/padding.stylex.ts
+++ b/packages/core/src/Layout/padding.stylex.ts
@@ -220,6 +220,58 @@ export const layoutPaddingOuterYVarStyles = stylex.create({
10: {'--layout-padding-outer-y': spacingVars['--spacing-10']},
});
+/**
+ * Inline-only padding styles.
+ * Use when a component needs to set inline (horizontal) padding independently
+ * of block padding — e.g. the `paddingX` prop on Stack.
+ */
+export const paddingInlineStyles = stylex.create({
+ 0: {
+ paddingInlineStart: spacingVars['--spacing-0'],
+ paddingInlineEnd: spacingVars['--spacing-0'],
+ },
+ 0.5: {
+ paddingInlineStart: spacingVars['--spacing-0-5'],
+ paddingInlineEnd: spacingVars['--spacing-0-5'],
+ },
+ 1: {
+ paddingInlineStart: spacingVars['--spacing-1'],
+ paddingInlineEnd: spacingVars['--spacing-1'],
+ },
+ 1.5: {
+ paddingInlineStart: spacingVars['--spacing-1-5'],
+ paddingInlineEnd: spacingVars['--spacing-1-5'],
+ },
+ 2: {
+ paddingInlineStart: spacingVars['--spacing-2'],
+ paddingInlineEnd: spacingVars['--spacing-2'],
+ },
+ 3: {
+ paddingInlineStart: spacingVars['--spacing-3'],
+ paddingInlineEnd: spacingVars['--spacing-3'],
+ },
+ 4: {
+ paddingInlineStart: spacingVars['--spacing-4'],
+ paddingInlineEnd: spacingVars['--spacing-4'],
+ },
+ 5: {
+ paddingInlineStart: spacingVars['--spacing-5'],
+ paddingInlineEnd: spacingVars['--spacing-5'],
+ },
+ 6: {
+ paddingInlineStart: spacingVars['--spacing-6'],
+ paddingInlineEnd: spacingVars['--spacing-6'],
+ },
+ 8: {
+ paddingInlineStart: spacingVars['--spacing-8'],
+ paddingInlineEnd: spacingVars['--spacing-8'],
+ },
+ 10: {
+ paddingInlineStart: spacingVars['--spacing-10'],
+ paddingInlineEnd: spacingVars['--spacing-10'],
+ },
+});
+
/**
* Block-only padding override styles.
* Use when a component needs to override block padding independently
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index 0508effc96..7322e87211 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -28,6 +28,31 @@ export const docs = {
description:
'Spacing step (number literal): 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10. Pass as a JSX number expression e.g. gap={4}, NOT a string like gap="4".',
},
+ {
+ name: 'padding',
+ type: 'SpacingStep',
+ description:
+ 'Inner padding on all sides, using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Matches the padding prop on Card, LayoutContent, and LayoutPanel. Pass as a JSX number expression e.g. padding={3}.',
+ },
+ {
+ name: 'paddingInline',
+ type: 'SpacingStep',
+ description:
+ 'Inline (horizontal) padding, using the spacing scale. Overrides padding on the inline axis when both are set.',
+ },
+ {
+ name: 'paddingBlock',
+ type: 'SpacingStep',
+ description:
+ 'Block (vertical) padding, using the spacing scale. Overrides padding on the block axis when both are set.',
+ },
+ {
+ name: 'isScrollable',
+ type: 'boolean',
+ description:
+ 'Enables scrollable overflow (overflow: auto). Matches isScrollable on LayoutContent and LayoutPanel.',
+ default: 'false',
+ },
{
name: 'width',
type: 'SizeValue',
@@ -96,6 +121,31 @@ export const docs = {
description:
'Spacing step (number literal): 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10. Pass as a JSX number expression e.g. gap={4}, NOT a string like gap="4".',
},
+ {
+ name: 'padding',
+ type: 'SpacingStep',
+ description:
+ 'Inner padding on all sides, using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Matches the padding prop on Card, LayoutContent, and LayoutPanel. Pass as a JSX number expression e.g. padding={3}.',
+ },
+ {
+ name: 'paddingInline',
+ type: 'SpacingStep',
+ description:
+ 'Inline (horizontal) padding, using the spacing scale. Overrides padding on the inline axis when both are set.',
+ },
+ {
+ name: 'paddingBlock',
+ type: 'SpacingStep',
+ description:
+ 'Block (vertical) padding, using the spacing scale. Overrides padding on the block axis when both are set.',
+ },
+ {
+ name: 'isScrollable',
+ type: 'boolean',
+ description:
+ 'Enables scrollable overflow (overflow: auto). Matches isScrollable on LayoutContent and LayoutPanel.',
+ default: 'false',
+ },
{
name: 'width',
type: 'SizeValue',
@@ -160,6 +210,13 @@ export const docs = {
'Flex grow behavior: static keeps natural size, fill expands to consume remaining space.',
default: "'static'",
},
+ {
+ name: 'isScrollable',
+ type: 'boolean',
+ description:
+ 'Enables scrollable overflow (overflow: auto). StackItem already applies the flex min-height/min-width reset, so <StackItem size="fill" isScrollable> is a complete scroll region. Matches isScrollable on LayoutContent and LayoutPanel.',
+ default: 'false',
+ },
{
name: 'crossAlignSelf',
type: "'start' | 'center' | 'end' | 'stretch'",
diff --git a/packages/core/src/Stack/Stack.test.tsx b/packages/core/src/Stack/Stack.test.tsx
index 2b07580ef6..4cc13b955e 100644
--- a/packages/core/src/Stack/Stack.test.tsx
+++ b/packages/core/src/Stack/Stack.test.tsx
@@ -253,15 +253,65 @@ describe('Stack', () => {
it('applies both width and height together', () => {
render(
- <Stack
- direction="vertical"
- width={400}
- height="100%"
- data-testid="stack">
+ <Stack direction="vertical" width={400} height="100%" data-testid="stack">
<div>Item</div>
</Stack>,
);
const el = screen.getByTestId('stack');
expect(el).toHaveStyle({width: '400px', height: '100%'});
});
+
+ it('applies a class when padding is set', () => {
+ render(
+ <Stack padding={3} data-testid="stack">
+ <div>Item</div>
+ </Stack>,
+ );
+ expect(screen.getByTestId('stack').className).not.toBe('');
+ });
+
+ it('accepts paddingInline and paddingBlock without error', () => {
+ render(
+ <Stack paddingInline={4} paddingBlock={2} data-testid="stack">
+ <div>Item</div>
+ </Stack>,
+ );
+ expect(screen.getByTestId('stack')).toBeInTheDocument();
+ });
+
+ it('lets paddingInline/paddingBlock override padding on their axis', () => {
+ // padding sets both axes; paddingInline overrides the inline axis. The
+ // component should render without conflict and carry a class.
+ render(
+ <Stack padding={2} paddingInline={5} data-testid="stack">
+ <div>Item</div>
+ </Stack>,
+ );
+ expect(screen.getByTestId('stack').className).not.toBe('');
+ });
+
+ it('applies a class when isScrollable is set', () => {
+ render(
+ <Stack isScrollable data-testid="stack">
+ <div>Item</div>
+ </Stack>,
+ );
+ expect(screen.getByTestId('stack').className).not.toBe('');
+ });
+
+ it('does not set overflow class when isScrollable is false', () => {
+ const {rerender} = render(
+ <Stack data-testid="stack">
+ <div>Item</div>
+ </Stack>,
+ );
+ const withoutScroll = screen.getByTestId('stack').className;
+ rerender(
+ <Stack isScrollable data-testid="stack">
+ <div>Item</div>
+ </Stack>,
+ );
+ const withScroll = screen.getByTestId('stack').className;
+ expect(withScroll).not.toBe(withoutScroll);
+ });
});
diff --git a/packages/core/src/Stack/Stack.tsx b/packages/core/src/Stack/Stack.tsx
index e36b355f17..7ecacf3892 100644
--- a/packages/core/src/Stack/Stack.tsx
+++ b/packages/core/src/Stack/Stack.tsx
@@ -25,9 +25,19 @@ import {
type SpacingStep,
} from './stack.stylex';
import type {SizeValue} from '../utils/types';
+import {
+ paddingInlineStyles,
+ paddingBlockStyles,
+} from '../Layout/padding.stylex';
import {mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
+const overflowStyles = stylex.create({
+ scrollable: {
+ overflow: 'auto',
+ },
+});
+
/**
* Alignment values accepted by Stack.
*
@@ -40,7 +50,6 @@ import {themeProps} from '../utils/themeProps';
*/
export type StackAlignment = StackMainAlignment | StackCrossAlignment;
-
export interface StackProps extends BaseProps<HTMLElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLElement>;
@@ -106,6 +115,37 @@ export interface StackProps extends BaseProps<HTMLElement> {
*/
gap?: SpacingStep;
+ /**
+ * Inner padding on all sides, using the spacing scale.
+ * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
+ *
+ * Matches the `padding` prop on `Card`, `LayoutContent`, and `LayoutPanel`.
+ */
+ padding?: SpacingStep;
+
+ /**
+ * Inline (horizontal) padding, using the spacing scale.
+ * Overrides `padding` on the inline axis when both are set.
+ */
+ paddingInline?: SpacingStep;
+
+ /**
+ * Block (vertical) padding, using the spacing scale.
+ * Overrides `padding` on the block axis when both are set.
+ */
+ paddingBlock?: SpacingStep;
+
+ /**
+ * Enables scrollable overflow (`overflow: auto`) for the stack.
+ *
+ * Matches the `isScrollable` prop on `LayoutContent` and `LayoutPanel`.
+ * When the stack is itself a flex child that should scroll, pair it with
+ * a parent `StackItem size="fill" isScrollable` (StackItem applies the
+ * `min-height: 0` reset that flex scroll regions require).
+ * @default false
+ */
+ isScrollable?: boolean;
+
/**
* Whether items should wrap.
* - `nowrap`: Items stay on one line (default)
@@ -180,6 +220,10 @@ export function Stack({
justify,
align,
gap,
+ padding,
+ paddingInline,
+ paddingBlock,
+ isScrollable,
width,
height,
wrap,
@@ -207,6 +251,11 @@ export function Stack({
? (resolvedVAlign as StackCrossAlignment | undefined)
: (resolvedHAlign as StackCrossAlignment | undefined);
+ // Resolve padding to per-axis values: `padding` sets both axes; `paddingInline`
+ // / `paddingBlock` take precedence on their own axis when provided.
+ const resolvedPaddingInline = paddingInline ?? padding;
+ const resolvedPaddingBlock = paddingBlock ?? padding;
+
const stylexProps = stylex.props(
...stack({
direction,
@@ -215,6 +264,9 @@ export function Stack({
gap,
wrap,
}),
+ resolvedPaddingInline != null && paddingInlineStyles[resolvedPaddingInline],
+ resolvedPaddingBlock != null && paddingBlockStyles[resolvedPaddingBlock],
+ isScrollable && overflowStyles.scrollable,
xstyle,
);
diff --git a/packages/core/src/Stack/StackItem.test.tsx b/packages/core/src/Stack/StackItem.test.tsx
index 8f1363033c..a5d0fa0e23 100644
--- a/packages/core/src/Stack/StackItem.test.tsx
+++ b/packages/core/src/Stack/StackItem.test.tsx
@@ -79,4 +79,27 @@ describe('StackItem', () => {
const element = screen.getByTestId('stack-item');
expect(element).toHaveAttribute('aria-label', 'Stack item');
});
+
+ it('applies an overflow class when isScrollable is set', () => {
+ const {rerender} = render(
+ <StackItem data-testid="stack-item">Content</StackItem>,
+ );
+ const withoutScroll = screen.getByTestId('stack-item').className;
+ rerender(
+ <StackItem isScrollable data-testid="stack-item">
+ Content
+ </StackItem>,
+ );
+ const withScroll = screen.getByTestId('stack-item').className;
+ expect(withScroll).not.toBe(withoutScroll);
+ });
+
+ it('composes isScrollable with size="fill"', () => {
+ render(
+ <StackItem size="fill" isScrollable data-testid="stack-item">
+ Content
+ </StackItem>,
+ );
+ expect(screen.getByTestId('stack-item').className).not.toBe('');
+ });
});
diff --git a/packages/core/src/Stack/StackItem.tsx b/packages/core/src/Stack/StackItem.tsx
index 6bca37521a..32c072f5f9 100644
--- a/packages/core/src/Stack/StackItem.tsx
+++ b/packages/core/src/Stack/StackItem.tsx
@@ -23,6 +23,12 @@ import {
import {mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
+const overflowStyles = stylex.create({
+ scrollable: {
+ overflow: 'auto',
+ },
+});
+
export interface StackItemProps extends BaseProps<HTMLElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLElement>;
@@ -41,6 +47,18 @@ export interface StackItemProps extends BaseProps<HTMLElement> {
*/
size?: StackItemSize;
+ /**
+ * Enables scrollable overflow (`overflow: auto`) for the item.
+ *
+ * StackItem already applies the flex `min-height: 0` / `min-width: 0`
+ * reset, so `<StackItem size="fill" isScrollable>` is a complete scroll
+ * region — it grows to fill the stack and scrolls its own overflow with
+ * no extra style plumbing. Matches `isScrollable` on `LayoutContent`
+ * and `LayoutPanel`.
+ * @default false
+ */
+ isScrollable?: boolean;
+
/**
* The element type to render.
* @default 'div'
@@ -92,6 +110,7 @@ export interface StackItemProps extends BaseProps<HTMLElement> {
export function StackItem({
crossAlignSelf,
size,
+ isScrollable,
as: element = 'div',
xstyle,
className,
@@ -102,6 +121,7 @@ export function StackItem({
}: StackItemProps) {
const stylexProps = stylex.props(
...stackItem({crossAlignSelf, size}),
+ isScrollable && overflowStyles.scrollable,
xstyle,
);