diff --git a/.changeset/thin-eagles-sparkle.md b/.changeset/thin-eagles-sparkle.md
new file mode 100644
index 00000000000..de41a2a4d5d
--- /dev/null
+++ b/.changeset/thin-eagles-sparkle.md
@@ -0,0 +1,5 @@
+---
+"@itwin/itwinui-react": minor
+---
+
+Added a new `stretch` prop to `Button` to allow it to span the full width of its container.
diff --git a/apps/react-workshop/cypress-visual-screenshots/baseline/Button.test.ts-Stretch.png b/apps/react-workshop/cypress-visual-screenshots/baseline/Button.test.ts-Stretch.png
new file mode 100755
index 00000000000..aca790567a6
Binary files /dev/null and b/apps/react-workshop/cypress-visual-screenshots/baseline/Button.test.ts-Stretch.png differ
diff --git a/apps/react-workshop/src/Button.stories.tsx b/apps/react-workshop/src/Button.stories.tsx
index 0033c94ab3b..8e66f33379e 100644
--- a/apps/react-workshop/src/Button.stories.tsx
+++ b/apps/react-workshop/src/Button.stories.tsx
@@ -113,3 +113,14 @@ export const AsLink = () => {
);
};
+
+export const Stretch = () => {
+ return ;
+};
+Stretch.decorators = [
+ (Story: () => React.ReactNode) => (
+
+
+
+ ),
+];
diff --git a/apps/react-workshop/src/Button.test.ts b/apps/react-workshop/src/Button.test.ts
index c5e5349ef83..f8d801ec0d6 100644
--- a/apps/react-workshop/src/Button.test.ts
+++ b/apps/react-workshop/src/Button.test.ts
@@ -13,6 +13,7 @@ describe('Button', () => {
'With Icon',
'Call To Action',
'As Link',
+ 'Stretch',
];
tests.forEach((testName) => {
diff --git a/apps/website/src/content/docs/button.mdx b/apps/website/src/content/docs/button.mdx
index 1bb2678b87e..50112a7f369 100644
--- a/apps/website/src/content/docs/button.mdx
+++ b/apps/website/src/content/docs/button.mdx
@@ -18,9 +18,7 @@ thumbnail: Button
Buttons have states and events and should be used when a form is submitted or where the button represents a clear call to action on a page.
In some cases, buttons can also be used in place of href links to draw special attention to that action.
-## Variants
-
-### Default
+## Usage
The default button should be used in most circumstances. If you are unsure as to what button to use, use this button!
@@ -65,6 +63,16 @@ There are 3 different sizes available, which can be applied to any button. The m
+### Stretch
+
+To make a button stretch to the full width of its parent, use the `stretch` prop.
+
+```jsx
+
+```
+
+This is useful in narrow containers and mobile views. Don't overuse this!
+
## Button props
@@ -119,7 +127,7 @@ If the button does obscure anything important, we suggest adding empty space at
-## Usage
+## Usage guidelines
### Style types
diff --git a/packages/itwinui-react/src/core/Buttons/Button.test.tsx b/packages/itwinui-react/src/core/Buttons/Button.test.tsx
index 2c0a38b8d35..418b5de442e 100644
--- a/packages/itwinui-react/src/core/Buttons/Button.test.tsx
+++ b/packages/itwinui-react/src/core/Buttons/Button.test.tsx
@@ -215,3 +215,8 @@ it('should render [x]Props correctly', () => {
expect(labelElement).toBeTruthy();
expect(labelElement.style.width).toBe('80px');
});
+
+it('should respect `stretch` prop', () => {
+ const { container } = render();
+ expect(container.querySelector('button')).toHaveStyle('--_iui-width: 100%');
+});
diff --git a/packages/itwinui-react/src/core/Buttons/Button.tsx b/packages/itwinui-react/src/core/Buttons/Button.tsx
index 7fed39b026c..e49413d7daa 100644
--- a/packages/itwinui-react/src/core/Buttons/Button.tsx
+++ b/packages/itwinui-react/src/core/Buttons/Button.tsx
@@ -39,6 +39,12 @@ export type ButtonProps = {
* Passes props to the end icon.
*/
endIconProps?: React.ComponentProps<'span'>;
+ /**
+ * Whether the button should stretch to fill the width of the container.
+ *
+ * This is useful on narrow containers and mobile views.
+ */
+ stretch?: boolean;
} & Pick, 'htmlDisabled'>;
/**
@@ -61,6 +67,7 @@ export const Button = React.forwardRef((props, ref) => {
labelProps,
startIconProps,
endIconProps,
+ stretch,
...rest
} = props;
@@ -71,6 +78,12 @@ export const Button = React.forwardRef((props, ref) => {
data-iui-variant={styleType !== 'default' ? styleType : undefined}
data-iui-size={size}
{...rest}
+ style={
+ {
+ '--_iui-width': stretch ? '100%' : undefined,
+ ...props.style,
+ } as React.CSSProperties
+ }
>
{startIcon && (