Skip to content

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

TypeScript

feat(core): add Button width prop (#3875)

Jiun Shin502aac2bbb4e
diff --git a/.changeset/button-new-width-prop-following-the-input-field--p14h.md b/.changeset/button-new-width-prop-following-the-input-field--p14h.md
new file mode 100644
index 0000000000..5cbf3b3d12
--- /dev/null
+++ b/.changeset/button-new-width-prop-following-the-input-field--p14h.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Button: new `width` prop following the input field width convention (`SizeValue`: numbers are pixels, strings are used as-is). `width="100%"` removes the need for a `width: '100%'` xstyle override or a stretch layout wrapper for full-width CTAs in auth forms, dialogs, and mobile layouts (#2600).
+@jiunshinn
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
index e73382749c..cb8ec82f9c 100644
--- a/packages/core/src/Button/Button.doc.mjs
+++ b/packages/core/src/Button/Button.doc.mjs
@@ -104,6 +104,12 @@ export const docs = {
'When true, renders as a square icon-only button with label as aria-label. Requires icon. Tip: for a dedicated icon-only button component, use IconButton from \'@astryxdesign/core/IconButton\' instead.',
default: 'false',
},
+ {
+ name: 'width',
+ type: 'SizeValue',
+ description:
+ "Width of the button. Numbers are treated as pixels, strings are used as-is (e.g., '100%' for a full-width button). By default the button sizes to its content.",
+ },
{
name: 'children',
type: 'ReactNode',
@@ -205,6 +211,7 @@ export const docsZh = {
default: 'false',
},
{name: 'icon', type: 'ReactNode', description: '图标元素。仅提供 icon 而不提供 children 时,按钮渲染为正方形的纯图标按钮。'},
+ {name: 'width', type: 'SizeValue', description: "按钮宽度。数字按像素处理,字符串按原样使用(如 '100%' 表示全宽按钮)。默认按内容自适应宽度。"},
{name: 'children', type: 'ReactNode', description: '可选的可见内容覆盖;label 仍然是必需的(用于无障碍名称)。大多数情况使用 <Button label="Save" />。'},
{
name: 'endContent',
@@ -272,6 +279,7 @@ export const docsDense = {
isLoading: 'shows spinner+disables interaction; announces via live region',
icon: 'icon element rendered before label text',
isIconOnly: 'when true, renders square icon-only button; label becomes aria-label',
+ width: "Width of button. Numbers=pixels, strings=as-is (e.g. '100%' for full-width).",
children: 'optional visible override; label is still required for a11y. Prefer <Button label="Save" /> over using children',
endContent: 'trailing icon/badge after label; ignored when isIconOnly; color inherited',
tooltip: 'tooltip on hover',
diff --git a/packages/core/src/Button/Button.test.tsx b/packages/core/src/Button/Button.test.tsx
index 52829ca8ba..adceca6c6e 100644
--- a/packages/core/src/Button/Button.test.tsx
+++ b/packages/core/src/Button/Button.test.tsx
@@ -243,6 +243,33 @@ describe('Button', () => {
expect(button).toHaveAttribute('data-size', 'sm');
});
+ it('applies string width as-is', () => {
+ render(<Button label="Sign in" width="100%" />);
+ const button = screen.getByRole('button');
+ // StyleX compiles the dynamic width to an inline CSS custom property.
+ expect(button.getAttribute('style')).toContain('100%');
+ expect(button.className).toContain('dynamicStyles.width');
+ });
+
+ it('applies numeric width as pixels', () => {
+ render(<Button label="Sign in" width={240} />);
+ expect(screen.getByRole('button').getAttribute('style')).toContain('240');
+ });
+
+ it('omits width styling when the prop is not provided', () => {
+ render(<Button label="Sign in" />);
+ expect(screen.getByRole('button').className).not.toContain(
+ 'dynamicStyles.width',
+ );
+ });
+
+ it('applies width when rendered as a link via href', () => {
+ render(<Button label="Sign in" href="https://example.com" width="100%" />);
+ expect(
+ screen.getByRole('link', {name: 'Sign in'}).getAttribute('style'),
+ ).toContain('100%');
+ });
+
// P0: onClick fires before clickAction, clickAction respects preventDefault
it('fires onClick before clickAction', async () => {
const user = userEvent.setup();
diff --git a/packages/core/src/Button/Button.tsx b/packages/core/src/Button/Button.tsx
index 43b46b448c..f84f85ae45 100644
--- a/packages/core/src/Button/Button.tsx
+++ b/packages/core/src/Button/Button.tsx
@@ -15,11 +15,12 @@
* - /apps/storybook/stories/Button.stories.tsx (storybook stories)
* - /packages/cli/templates/blocks/components/Button/ (showcase blocks)
*
- * Last synced props: label, variant, size, isDisabled, isLoading, isInterruptible, clickAction, icon, isIconOnly, children, tooltip, endContent, href, as, target, rel
+ * Last synced props: label, variant, size, isDisabled, isLoading, isInterruptible, clickAction, icon, isIconOnly, width, children, tooltip, endContent, href, as, target, rel
*/
import {useRef, useTransition, type ReactNode} from 'react';
import type {BaseProps} from '../BaseProps';
+import type {SizeValue} from '../utils/types';
import * as stylex from '@stylexjs/stylex';
import {useTooltip} from '../Tooltip/useTooltip';
import {
@@ -130,6 +131,12 @@ const styles = stylex.create({
},
});
+// Dynamic style for the consumer-controlled button width. Numbers are treated
+// as pixels by StyleX; strings (e.g. '100%') are used as-is.
+const dynamicStyles = stylex.create({
+ width: (width: SizeValue | null) => ({width}),
+});
+
const sizeStyles = stylex.create({
sm: {
height: sizeVars['--size-element-sm'],
@@ -341,6 +348,12 @@ export interface ButtonProps extends BaseProps<HTMLButtonElement> {
* @default false
*/
isIconOnly?: boolean;
+ /**
+ * Width of the button. Numbers are treated as pixels, strings are used as-is
+ * (e.g. `'100%'` for a full-width button). By default the button sizes to
+ * its content.
+ */
+ width?: SizeValue;
/**
* Optional visible content. When provided, rendered instead of `label` as the
* visible text (label still serves as the accessible name via aria-label).
@@ -548,6 +561,7 @@ const groupStyles = stylex.create({
* <Button label="Edit" icon={<PencilIcon />} />
* <Button label="Messages" endContent={<Badge label={3} />} />
* <Button label="Edit" icon={<PencilIcon />} endContent={<Badge label="New" />} />
+ * <Button label="Sign in" variant="primary" width="100%" />
* <Button label="Visit site" href="https://example.com" variant="primary" />
* <Button label="Open in new tab" href="https://example.com" target="_blank" rel="noopener noreferrer" />
* ```
@@ -563,6 +577,7 @@ export function Button({
clickAction,
icon,
isIconOnly = false,
+ width,
children,
endContent,
tooltip,
@@ -676,6 +691,7 @@ export function Button({
(buttonGroup.orientation === 'horizontal'
? groupStyles.onSolidHorizontal
: groupStyles.onSolidVertical),
+ width != null && dynamicStyles.width(width),
xstyle,
);