Add labelPlacement prop to IconButton and ToggleButton components (#1442)

GerardasB · web-flow · commit 952a988d21c8 · 2026-04-23T16:21:47.000+03:00
diff --git a/.changeset/humble-gifts-appear.md b/.changeset/humble-gifts-appear.md
@@ -0,0 +1,5 @@
+---
+"@stratakit/mui": patch
+---
+
+Added a new `labelPlacement` prop to `IconButton` and `ToggleButton` components to control the placement of a tooltip that is shown when the `label` prop is specified.
diff --git a/apps/test-app/app/mui.tsx b/apps/test-app/app/mui.tsx
@@ -66,6 +66,7 @@ import DividerVertical from "examples/mui/Divider.vertical.tsx";
 import DrawerDefault from "examples/mui/Drawer.default.tsx";
 import FabDefault from "examples/mui/Fab.default.tsx";
 import IconButtonColors_ from "examples/mui/IconButton._colors.tsx";
+import IconButtonPlacements_ from "examples/mui/IconButton._placements.tsx";
 import IconButtonDefault from "examples/mui/IconButton.default.tsx";
 import IconButtonSizes from "examples/mui/IconButton.sizes.tsx";
 import LinearProgressColors_ from "examples/mui/LinearProgress._colors.tsx";
@@ -116,6 +117,7 @@ import TextFieldIcon from "examples/mui/TextField.icon.tsx";
 import TextFieldMultiline from "examples/mui/TextField.multiline.tsx";
 import TextFieldSizes from "examples/mui/TextField.sizes.tsx";
 import ToggleButtonDisabled_ from "examples/mui/ToggleButton._disabled.tsx";
+import ToggleButtonPlacements_ from "examples/mui/ToggleButton._placements.tsx";
 import ToggleButtonDefault from "examples/mui/ToggleButton.default.tsx";
 import ToggleButtonSizes from "examples/mui/ToggleButton.sizes.tsx";
 import ToggleButtonStandalone from "examples/mui/ToggleButton.standalone.tsx";
@@ -274,6 +276,11 @@ const components: Record<string, React.ReactNode> = {
 					<IconButtonColors_ />
 				</Stack>
 			)}
+			{!isProduction && (
+				<Stack spacing={1} direction="row">
+					<IconButtonPlacements_ />
+				</Stack>
+			)}
 		</>
 	),
 	LinearProgress: (
@@ -390,6 +397,11 @@ const components: Record<string, React.ReactNode> = {
 			<ToggleButtonSizes />
 			<ToggleButtonDisabled_ />
 			<ToggleButtonText />
+			{!isProduction && (
+				<Stack spacing={1} direction="row">
+					<ToggleButtonPlacements_ />
+				</Stack>
+			)}
 		</>
 	),
 	Tooltip: (
diff --git a/apps/website/src/content/docs/components/mui/IconButton.md b/apps/website/src/content/docs/components/mui/IconButton.md
@@ -25,6 +25,7 @@ Make sure the **IconButton** is suitable for your use case. There may be other,
 - The `"default"`, `"info"`, `"success"`, `"warning"`, `"inherit"` colors have been removed. The default color is now `"secondary"`.
 - The `size` options (`"small"`, `"medium"`, `"large"`) have all been decreased in height.
 - A `label` prop has been added. When specified, it is used as the **IconButton’s** accessible name and is also shown in a tooltip on hover and focus.
+- A `labelPlacement` prop has been added to control the placement of a tooltip that is shown when the `label` prop is specified.
 
 ## Examples
 
diff --git a/apps/website/src/content/docs/components/mui/ToggleButton.md b/apps/website/src/content/docs/components/mui/ToggleButton.md
@@ -11,6 +11,7 @@ links:
 ## StrataKit MUI modifications
 
 - A `label` prop has been added. When specified, it is used as the **ToggleButton’s** accessible name and is also shown in a tooltip on hover and focus.
+- A `labelPlacement` prop has been added to control the placement of a tooltip that is shown when the `label` prop is specified.
 - **ToggleButtons** are styled to match the visual appearance of the [**IconButton**](/components/iconbutton) component. Borders are displayed only when the buttons are wrapped in a `ToggleButtonGroup`. [Standalone](#standalone) **ToggleButtons** do not have borders.
 - **ToggleButtons** can now be rendered as regular [**Buttons**](/components/button) to [display text](#text).
 
diff --git a/examples/mui/IconButton._placements.tsx b/examples/mui/IconButton._placements.tsx
@@ -0,0 +1,29 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+
+import IconButton from "@mui/material/IconButton";
+import { Icon } from "@stratakit/mui";
+
+import svgPlaceholder from "@stratakit/icons/placeholder.svg";
+
+type IconButtonProps = React.ComponentProps<typeof IconButton>;
+const placements = [
+	"top",
+	"right",
+	"bottom",
+	"left",
+] as const satisfies IconButtonProps["labelPlacement"][];
+
+export default () => {
+	return placements.map((placement) => (
+		<IconButton
+			key={placement}
+			label={`${placement.charAt(0).toUpperCase()}${placement.slice(1)}`}
+			labelPlacement={placement}
+		>
+			<Icon href={svgPlaceholder} />
+		</IconButton>
+	));
+};
diff --git a/examples/mui/ToggleButton._placements.tsx b/examples/mui/ToggleButton._placements.tsx
@@ -0,0 +1,40 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+
+import * as React from "react";
+import ToggleButton from "@mui/material/ToggleButton";
+import { Icon } from "@stratakit/mui";
+
+import svgPlaceholder from "@stratakit/icons/placeholder.svg";
+
+type ToggleButtonProps = React.ComponentProps<typeof ToggleButton>;
+const placements = [
+	"top",
+	"right",
+	"bottom",
+	"left",
+] as const satisfies ToggleButtonProps["labelPlacement"][];
+
+export default () => {
+	const [selected, setSelected] = React.useState<string[]>([]);
+	return placements.map((placement) => (
+		<ToggleButton
+			key={placement}
+			value={placement}
+			label={`${placement.charAt(0).toUpperCase()}${placement.slice(1)}`}
+			labelPlacement={placement}
+			selected={selected.includes(placement)}
+			onChange={() =>
+				setSelected((prev) =>
+					prev.includes(placement)
+						? prev.filter((p) => p !== placement)
+						: [...prev, placement],
+				)
+			}
+		>
+			<Icon href={svgPlaceholder} />
+		</ToggleButton>
+	));
+};
diff --git a/packages/mui/src/types.ts b/packages/mui/src/types.ts
@@ -16,6 +16,7 @@ import type {
 	TextFieldProps,
 	TextFieldVariants,
 } from "@mui/material/TextField";
+import type { TooltipProps } from "@mui/material/Tooltip";
 import type { TypographyProps } from "@mui/material/Typography";
 import type * as React from "react";
 
@@ -224,6 +225,13 @@ declare module "@mui/material/IconButton" {
 		 * If not specified, the accessible name and tooltip must be wired up manually.
 		 */
 		label?: string;
+
+		/**
+		 * Placement of the tooltip that is shown when the `label` prop is specified.
+		 *
+		 * @default 'top'
+		 */
+		labelPlacement?: TooltipProps["placement"];
 	}
 }
 
@@ -336,6 +344,13 @@ declare module "@mui/material/ToggleButton" {
 		 * Should only be provided when the toggle button does not have visible text content that can serve as an accessible name.
 		 */
 		label?: IconButtonProps["label"];
+
+		/**
+		 * Placement of the tooltip that is shown when the `label` prop is specified.
+		 *
+		 * @default 'top'
+		 */
+		labelPlacement?: TooltipProps["placement"];
 	}
 }
 
diff --git a/packages/mui/src/~components/MuiIconButton.tsx b/packages/mui/src/~components/MuiIconButton.tsx
@@ -14,15 +14,15 @@ import type { BaseProps } from "@stratakit/foundations/secret-internals";
 
 interface MuiIconButtonProps
 	extends BaseProps<"button">,
-		Pick<IconButtonOwnProps, "label"> {}
+		Pick<IconButtonOwnProps, "label" | "labelPlacement"> {}
 
 const MuiIconButton = forwardRef<"button", MuiIconButtonProps>(
 	(props, forwardedRef) => {
-		const { label, ...rest } = props;
+		const { label, labelPlacement, ...rest } = props;
 
 		if (label) {
 			return (
-				<Tooltip title={label} describeChild={false}>
+				<Tooltip title={label} describeChild={false} placement={labelPlacement}>
 					<MuiButtonBase {...rest} ref={forwardedRef} />
 				</Tooltip>
 			);
diff --git a/packages/mui/src/~components/MuiToggleButton.tsx b/packages/mui/src/~components/MuiToggleButton.tsx
@@ -15,11 +15,11 @@ import type { BaseProps } from "@stratakit/foundations/secret-internals";
 
 interface MuiToggleButtonProps
 	extends BaseProps<"button">,
-		Pick<ToggleButtonOwnProps, "label"> {}
+		Pick<ToggleButtonOwnProps, "label" | "labelPlacement"> {}
 
 const MuiToggleButton = forwardRef<"button", MuiToggleButtonProps>(
 	(props, forwardedRef) => {
-		const { label, ...rest } = props;
+		const { label, labelPlacement, ...rest } = props;
 
 		const classList = props.className?.split(" ") ?? [];
 		const size = (() => {
@@ -31,7 +31,7 @@ const MuiToggleButton = forwardRef<"button", MuiToggleButtonProps>(
 
 		if (label) {
 			return (
-				<Tooltip title={label} describeChild={false}>
+				<Tooltip title={label} describeChild={false} placement={labelPlacement}>
 					<MuiButtonBase
 						{...rest}
 						render={props.render ?? <IconButton size={size} />}

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@stratakit/mui": patch
 +---
++
 +Added a new `labelPlacement` prop to `IconButton` and `ToggleButton` components to control the placement of a tooltip that is shown when the `label` prop is specified.