Skip to content

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

TypeScript

feat(InputGroup): add XDSInputGroup component (#220) (#2207)

Andrey Godera761d5b2210e
diff --git a/apps/storybook/stories/InputGroup.stories.tsx b/apps/storybook/stories/InputGroup.stories.tsx
new file mode 100644
index 0000000000..d1ee08a166
--- /dev/null
+++ b/apps/storybook/stories/InputGroup.stories.tsx
@@ -0,0 +1,319 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSInputGroup} from '@xds/core/InputGroup';
+import {XDSInputGroupText} from '@xds/core/InputGroup';
+import {XDSTextInput} from '@xds/core/TextInput';
+import {XDSNumberInput} from '@xds/core/NumberInput';
+import {XDSIcon} from '@xds/core/Icon';
+
+const meta: Meta<typeof XDSInputGroup> = {
+ title: 'Core/Inputs/InputGroup',
+ component: XDSInputGroup,
+ tags: ['autodocs'],
+ argTypes: {
+ label: {control: 'text', description: 'Label text (required)'},
+ isLabelHidden: {control: 'boolean', description: 'Visually hide the label'},
+ description: {control: 'text', description: 'Description text'},
+ isDisabled: {control: 'boolean', description: 'Disable the group'},
+ size: {
+ control: 'radio',
+ options: ['sm', 'md', 'lg'],
+ description: 'Input size',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSInputGroup>;
+
+export const WithPrefix: Story = {
+ render: args => {
+ const [value, setValue] = useState('');
+ return (
+ <XDSInputGroup {...args}>
+ <XDSInputGroupText>$</XDSInputGroupText>
+ <XDSTextInput
+ label="Amount"
+ isLabelHidden
+ value={value}
+ onChange={setValue}
+ placeholder="0.00"
+ />
+ </XDSInputGroup>
+ );
+ },
+ args: {
+ label: 'Price',
+ },
+};
+
+export const WithSuffix: Story = {
+ render: args => {
+ const [value, setValue] = useState('');
+ return (
+ <XDSInputGroup {...args}>
+ <XDSTextInput
+ label="Weight"
+ isLabelHidden
+ value={value}
+ onChange={setValue}
+ placeholder="0"
+ />
+ <XDSInputGroupText>kg</XDSInputGroupText>
+ </XDSInputGroup>
+ );
+ },
+ args: {
+ label: 'Weight',
+ },
+};
+
+export const WithPrefixAndSuffix: Story = {
+ render: args => {
+ const [value, setValue] = useState('');
+ return (
+ <XDSInputGroup {...args}>
+ <XDSInputGroupText>https://</XDSInputGroupText>
+ <XDSTextInput
+ label="URL"
+ isLabelHidden
+ value={value}
+ onChange={setValue}
+ placeholder="example"
+ />
+ <XDSInputGroupText>.com</XDSInputGroupText>
+ </XDSInputGroup>
+ );
+ },
+ args: {
+ label: 'Website',
+ },
+};
+
+export const WithIconPrefix: Story = {
+ render: args => {
+ const [value, setValue] = useState('');
+ return (
+ <XDSInputGroup {...args}>
+ <XDSInputGroupText>
+ <XDSIcon icon="search" size="sm" color="secondary" />
+ </XDSInputGroupText>
+ <XDSTextInput
+ label="Search"
+ isLabelHidden
+ value={value}
+ onChange={setValue}
+ placeholder="Search..."
+ />
+ </XDSInputGroup>
+ );
+ },
+ args: {
+ label: 'Search',
+ isLabelHidden: true,
+ },
+};
+
+export const WithNumberInput: Story = {
+ render: args => {
+ const [value, setValue] = useState<number | undefined>(undefined);
+ return (
+ <XDSInputGroup {...args}>
+ <XDSInputGroupText>$</XDSInputGroupText>
+ <XDSNumberInput
+ label="Amount"
+ isLabelHidden
+ value={value}
+ onChange={setValue}
+ placeholder="0.00"
+ />
+ </XDSInputGroup>
+ );
+ },
+ args: {
+ label: 'Budget',
+ },
+};
+
+export const WithDescription: Story = {
+ render: args => {
+ const [value, setValue] = useState('');
+ return (
+ <XDSInputGroup {...args}>
+ <XDSInputGroupText>@</XDSInputGroupText>
+ <XDSTextInput
+ label="Username"
+ isLabelHidden
+ value={value}
+ onChange={setValue}
+ placeholder="username"
+ />
+ </XDSInputGroup>
+ );
+ },
+ args: {
+ label: 'Username',
+ description: 'Your public display name',
+ },
+};
+
+export const WithErrorStatus: Story = {
+ render: args => {
+ const [value, setValue] = useState('');
+ return (
+ <XDSInputGroup {...args}>
+ <XDSInputGroupText>$</XDSInputGroupText>
+ <XDSTextInput
+ label="Amount"
+ isLabelHidden
+ value={value}
+ onChange={setValue}
+ placeholder="0.00"
+ />
+ </XDSInputGroup>
+ );
+ },
+ args: {
+ label: 'Price',
+ status: {type: 'error', message: 'Price is required'},
+ },
+};
+
+export const SmallSize: Story = {
+ render: args => {
+ const [value, setValue] = useState('');
+ return (
+ <XDSInputGroup {...args}>
+ <XDSInputGroupText>$</XDSInputGroupText>
+ <XDSTextInput
+ label="Amount"
+ isLabelHidden
+ value={value}
+ onChange={setValue}
+ placeholder="0.00"
+ />
+ </XDSInputGroup>
+ );
+ },
+ args: {
+ label: 'Price',
+ size: 'sm',
+ },
+};
+
+export const FullWidth: Story = {
+ render: args => {
+ const [value, setValue] = useState('');
+ return (
+ <div style={{maxWidth: 500}}>
+ <XDSInputGroup {...args}>
+ <XDSInputGroupText>https://</XDSInputGroupText>
+ <XDSTextInput
+ label="URL"
+ isLabelHidden
+ value={value}
+ onChange={setValue}
+ placeholder="example.com"
+ />
+ </XDSInputGroup>
+ </div>
+ );
+ },
+ args: {
+ label: 'Website URL',
+ },
+};
+
+export const TwoInputs: Story = {
+ render: args => {
+ const [left, setLeft] = useState('');
+ const [right, setRight] = useState('');
+ return (
+ <XDSInputGroup {...args}>
+ <XDSTextInput
+ label="Address"
+ isLabelHidden
+ value={left}
+ onChange={setLeft}
+ placeholder="Address"
+ />
+ <XDSInputGroupText>@</XDSInputGroupText>
+ <XDSTextInput
+ label="Domain"
+ isLabelHidden
+ value={right}
+ onChange={setRight}
+ placeholder="Domain"
+ />
+ </XDSInputGroup>
+ );
+ },
+ args: {
+ label: 'Email',
+ },
+};
+
+export const AllVariations: Story = {
+ render: () => {
+ const [v1, setV1] = useState('');
+ const [v2, setV2] = useState('');
+ const [v3, setV3] = useState('');
+ const [v4, setV4] = useState('');
+
+ return (
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '16px',
+ maxWidth: '400px',
+ }}>
+ <XDSInputGroup label="Price">
+ <XDSInputGroupText>$</XDSInputGroupText>
+ <XDSTextInput
+ label="Amount"
+ isLabelHidden
+ value={v1}
+ onChange={setV1}
+ placeholder="0.00"
+ />
+ </XDSInputGroup>
+ <XDSInputGroup label="Website">
+ <XDSInputGroupText>https://</XDSInputGroupText>
+ <XDSTextInput
+ label="URL"
+ isLabelHidden
+ value={v2}
+ onChange={setV2}
+ placeholder="example"
+ />
+ <XDSInputGroupText>.com</XDSInputGroupText>
+ </XDSInputGroup>
+ <XDSInputGroup label="Weight">
+ <XDSTextInput
+ label="Weight"
+ isLabelHidden
+ value={v3}
+ onChange={setV3}
+ placeholder="0"
+ />
+ <XDSInputGroupText>kg</XDSInputGroupText>
+ </XDSInputGroup>
+ <XDSInputGroup
+ label="Price"
+ status={{type: 'error', message: 'Price is required'}}>
+ <XDSInputGroupText>$</XDSInputGroupText>
+ <XDSTextInput
+ label="Amount"
+ isLabelHidden
+ value={v4}
+ onChange={setV4}
+ placeholder="0.00"
+ />
+ </XDSInputGroup>
+ </div>
+ );
+ },
+};
diff --git a/packages/cli/templates/blocks/components/InputGroup/InputGroupShowcase.doc.mjs b/packages/cli/templates/blocks/components/InputGroup/InputGroupShowcase.doc.mjs
new file mode 100644
index 0000000000..ec8b258970
--- /dev/null
+++ b/packages/cli/templates/blocks/components/InputGroup/InputGroupShowcase.doc.mjs
@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'InputGroup',
+ name: 'InputGroup',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ isShowcase: true,
+ componentsUsed: ['InputGroup', 'TextInput', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/InputGroup/InputGroupShowcase.tsx b/packages/cli/templates/blocks/components/InputGroup/InputGroupShowcase.tsx
new file mode 100644
index 0000000000..9702b5de29
--- /dev/null
+++ b/packages/cli/templates/blocks/components/InputGroup/InputGroupShowcase.tsx
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {XDSInputGroup, XDSInputGroupText} from '@xds/core/InputGroup';
+import {XDSTextInput} from '@xds/core/TextInput';
+import {XDSStack} from '@xds/core/Layout';
+
+export default function InputGroupShowcase() {
+ const [price, setPrice] = useState('');
+ const [url, setUrl] = useState('');
+
+ return (
+ <XDSStack direction="vertical" gap={4} width="100%" style={{maxWidth: 400}}>
+ <XDSInputGroup label="Price">
+ <XDSInputGroupText>$</XDSInputGroupText>
+ <XDSTextInput
+ label="Amount"
+ isLabelHidden
+ value={price}
+ onChange={setPrice}
+ placeholder="0.00"
+ />
+ </XDSInputGroup>
+ <XDSInputGroup label="Website">
+ <XDSInputGroupText>https://</XDSInputGroupText>
+ <XDSTextInput
+ label="URL"
+ isLabelHidden
+ value={url}
+ onChange={setUrl}
+ placeholder="example"
+ />
+ <XDSInputGroupText>.com</XDSInputGroupText>
+ </XDSInputGroup>
+ </XDSStack>
+ );
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index 3be722a29e..482d554d47 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -289,6 +289,12 @@
"import": "./dist/IconButton/index.mjs",
"require": "./dist/IconButton/index.js"
},
+ "./InputGroup": {
+ "source": "./src/InputGroup/index.ts",
+ "types": "./dist/InputGroup/index.d.ts",
+ "import": "./dist/InputGroup/index.mjs",
+ "require": "./dist/InputGroup/index.js"
+ },
"./Kbd": {
"source": "./src/Kbd/index.ts",
"types": "./dist/Kbd/index.d.ts",
diff --git a/packages/core/src/InputGroup/InputGroup.doc.mjs b/packages/core/src/InputGroup/InputGroup.doc.mjs
new file mode 100644
index 0000000000..6a1b8a6ba2
--- /dev/null
+++ b/packages/core/src/InputGroup/InputGroup.doc.mjs
@@ -0,0 +1,104 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'InputGroup',
+ group: 'Field',
+ keywords: ["inputgroup","addon","prefix","suffix","connected","grouped","input"],
+ theming: {
+ targets: [
+ {className: 'xds-input-group', visualProps: ['size', 'status']},
+ ],
+ },
+ components: [
+ {
+ name: 'XDSInputGroup',
+ description: 'Groups an input with prefix/suffix addons in a visually connected container with shared border and focus ring.',
+ props: [
+ {name: 'children', type: 'ReactNode', description: 'Input and XDSInputGroupText children.', required: true},
+ {name: 'label', type: 'string', description: 'Accessible label for the group.', required: true},
+ {name: 'isLabelHidden', type: 'boolean', description: 'Visually hide the label.', default: 'false'},
+ {name: 'description', type: 'string', description: 'Helper text between label and input group.'},
+ {name: 'isDisabled', type: 'boolean', description: 'Disable the entire group.', default: 'false'},
+ {name: 'isOptional', type: 'boolean', description: 'Show "(optional)" indicator.', default: 'false'},
+ {name: 'isRequired', type: 'boolean', description: 'Mark the field as required.', default: 'false'},
+ {name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Default size for inputs in the group.', default: "'md'"},
+ {name: 'status', type: 'XDSInputStatus', description: 'Status indicator applied to the group border.'},
+ {name: 'labelTooltip', type: 'string', description: 'Tooltip text at the end of the label.'},
+ {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization.'},
+ {name: 'data-testid', type: 'string', description: 'Test selector.'},
+ ],
+ },
+ {
+ name: 'XDSInputGroupText',
+ description: 'A prefix or suffix text element rendered inside XDSInputGroup. Displays text or icons.',
+ props: [
+ {name: 'children', type: 'ReactNode', description: 'Text or icon content.', required: true},
+ {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for customization.'},
+ {name: 'className', type: 'string', description: 'CSS class name(s).'},
+ {name: 'style', type: 'React.CSSProperties', description: 'Inline styles.'},
+ ],
+ },
+ ],
+ usage: {
+ description: 'InputGroup connects an input with prefix/suffix addons in a single visual unit. Use it for URL fields, currency inputs, search fields with action buttons, or any input that needs contextual decorations.',
+ bestPractices: [
+ {guidance: true, description: 'Use text addons to show units, prefixes, or suffixes that clarify the input format (e.g., "$", "kg", "https://").'},
+ {guidance: true, description: 'Use XDSInputGroupText for static prefixes/suffixes like "$", "kg", or "https://".'},
+ {guidance: true, description: 'Set isLabelHidden on the inner input and let the group label be visible.'},
+ {guidance: false, description: 'Don\'t put multiple text inputs in one group — use separate fields instead.'},
+ {guidance: false, description: 'Don\'t use InputGroup for unrelated inputs — it\'s for a single input with decorations.'},
+ ],
+ anatomy: [
+ {name: 'Label', required: true, description: 'Text above the group.'},
+ {name: 'Prefix addon', required: false, description: 'Content before the input (text, icon, or button).'},
+ {name: 'Input', required: true, description: 'The main input element (XDSTextInput, XDSNumberInput, etc.).'},
+ {name: 'Suffix addon', required: false, description: 'Content after the input (text, icon, or button).'},
+ {name: 'Status message', required: false, description: 'An error, warning, or success message below the group.'},
+ ],
+ },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'groups input with prefix/suffix addons in a connected container',
+ usage: {
+ description: 'InputGroup connects an input with addons. Use for URL fields, currency inputs, search with actions.',
+ bestPractices: [
+ {guidance: true, description: 'Text addons for units/prefixes. isInteractive for buttons/selectors.'},
+ {guidance: true, description: 'isLabelHidden on inner input, group label visible.'},
+ {guidance: false, description: 'Don\'t put multiple inputs in one group. Don\'t group unrelated inputs.'},
+ ],
+ },
+ components: [
+ {
+ name: 'XDSInputGroup',
+ description: 'connected input+addon container w/ shared border, focus ring',
+ propDescriptions: {
+ children: 'input + addon children',
+ label: 'a11y label',
+ isLabelHidden: 'visually hide label',
+ description: 'helper text',
+ isDisabled: 'disable group',
+ isOptional: 'show "(optional)"',
+ isRequired: 'mark required',
+ size: 'default input size',
+ status: 'error/warning/success border',
+ labelTooltip: 'tooltip at label end',
+ xstyle: 'StyleX layout styles',
+ 'data-testid': 'test selector',
+ },
+ },
+ {
+ name: 'XDSInputGroupText',
+ description: 'prefix/suffix text/icon element',
+ propDescriptions: {
+ children: 'text or icon content',
+ xstyle: 'StyleX styles',
+ className: 'CSS class name(s)',
+ style: 'inline styles',
+ },
+ },
+ ],
+};
diff --git a/packages/core/src/InputGroup/XDSInputGroup.test.tsx b/packages/core/src/InputGroup/XDSInputGroup.test.tsx
new file mode 100644
index 0000000000..c3eb1e31dd
--- /dev/null
+++ b/packages/core/src/InputGroup/XDSInputGroup.test.tsx
@@ -0,0 +1,135 @@
+/**
+ * @file XDSInputGroup.test.tsx
+ * @input Uses vitest, @testing-library/react, InputGroup and TextInput components
+ * @output Unit tests for XDSInputGroup
+ * @position Testing; validates InputGroup component implementation
+ *
+ * SYNC: When InputGroup component changes, update tests to match new behavior
+ */
+
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSInputGroup} from './XDSInputGroup';
+import {XDSInputGroupText} from './XDSInputGroupText';
+import {XDSTextInput} from '../TextInput';
+
+describe('XDSInputGroup', () => {
+ it('renders a group with aria-label', () => {
+ render(
+ <XDSInputGroup label="Price">
+ <XDSInputGroupText>$</XDSInputGroupText>
+ <XDSTextInput label="Amount" isLabelHidden onChange={() => {}} />
+ </XDSInputGroup>,
+ );
+
+ const group = screen.getByRole('group');
+ expect(group).toBeInTheDocument();
+ expect(group).toHaveAttribute('aria-label', 'Price');
+ });
+
+ it('renders the visible label', () => {
+ render(
+ <XDSInputGroup label="Price">
+ <XDSTextInput label="Amount" isLabelHidden onChange={() => {}} />
+ </XDSInputGroup>,
+ );
+
+ expect(screen.getByText('Price')).toBeInTheDocument();
+ });
+
+ it('renders addon text', () => {
+ render(
+ <XDSInputGroup label="Price">
+ <XDSInputGroupText>$</XDSInputGroupText>
+ <XDSTextInput label="Amount" isLabelHidden onChange={() => {}} />
+ </XDSInputGroup>,
+ );
+
+ expect(screen.getByText('$')).toBeInTheDocument();
+ });
+
+ it('renders the input', () => {
+ render(
+ <XDSInputGroup label="Price">
+ <XDSTextInput label="Amount" isLabelHidden onChange={() => {}} />
+ </XDSInputGroup>,
+ );
+
+ expect(screen.getByRole('textbox')).toBeInTheDocument();
+ });
+
+ it('renders prefix and suffix addons', () => {
+ render(
+ <XDSInputGroup label="Website">
+ <XDSInputGroupText>https://</XDSInputGroupText>
+ <XDSTextInput label="URL" isLabelHidden onChange={() => {}} />
+ <XDSInputGroupText>.com</XDSInputGroupText>
+ </XDSInputGroup>,
+ );
+
+ expect(screen.getByText('https://')).toBeInTheDocument();
+ expect(screen.getByText('.com')).toBeInTheDocument();
+ expect(screen.getByRole('textbox')).toBeInTheDocument();
+ });
+
+ it('applies data-testid', () => {
+ render(
+ <XDSInputGroup label="Price" data-testid="price-group">
+ <XDSTextInput label="Amount" isLabelHidden onChange={() => {}} />
+ </XDSInputGroup>,
+ );
+
+ expect(screen.getByTestId('price-group')).toBeInTheDocument();
+ });
+
+ it('renders description text', () => {
+ render(
+ <XDSInputGroup label="Price" description="Enter the price in USD">
+ <XDSTextInput label="Amount" isLabelHidden onChange={() => {}} />
+ </XDSInputGroup>,
+ );
+
+ expect(screen.getByText('Enter the price in USD')).toBeInTheDocument();
+ });
+
+ it('renders status message', () => {
+ render(
+ <XDSInputGroup
+ label="Price"
+ status={{type: 'error', message: 'Price is required'}}>
+ <XDSTextInput label="Amount" isLabelHidden onChange={() => {}} />
+ </XDSInputGroup>,
+ );
+
+ expect(screen.getByText('Price is required')).toBeInTheDocument();
+ });
+
+ it('renders with hidden label', () => {
+ render(
+ <XDSInputGroup label="Price" isLabelHidden>
+ <XDSTextInput label="Amount" isLabelHidden onChange={() => {}} />
+ </XDSInputGroup>,
+ );
+
+ expect(screen.getByText('Price')).toBeInTheDocument();
+ expect(screen.getByRole('group')).toBeInTheDocument();
+ });
+
+ it('renders with different sizes', () => {
+ const {rerender} = render(
+ <XDSInputGroup label="Price" size="sm">
+ <XDSTextInput label="Amount" isLabelHidden onChange={() => {}} />
+ </XDSInputGroup>,
+ );
+ expect(screen.getByRole('textbox')).toBeInTheDocument();
+
+ rerender(
+ <XDSInputGroup label="Price" size="lg">
+ <XDSTextInput label="Amount" isLabelHidden onChange={() => {}} />
+ </XDSInputGroup>,
+ );
+ expect(screen.getByRole('textbox')).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/InputGroup/XDSInputGroup.tsx b/packages/core/src/InputGroup/XDSInputGroup.tsx
new file mode 100644
index 0000000000..57dd6daf62
--- /dev/null
+++ b/packages/core/src/InputGroup/XDSInputGroup.tsx
@@ -0,0 +1,212 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file XDSInputGroup.tsx
+ * @input Uses React, StyleX, theme tokens, InputGroupContext
+ * @output Exports XDSInputGroup component
+ * @position Groups input with prefix/suffix addons; consumed by index.ts
+ *
+ * Children (XDSTextInput, XDSNumberInput) consume the InputGroup context
+ * to remove their own border/radius so the group container provides
+ * the unified border treatment.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/InputGroup/InputGroup.doc.mjs
+ * - /packages/core/src/InputGroup/XDSInputGroup.test.tsx
+ * - /packages/core/src/InputGroup/index.ts
+ * - /apps/storybook/stories/InputGroup.stories.tsx
+ * - /packages/cli/templates/blocks/components/InputGroup/
+ */
+
+import {useId, useMemo, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {sizeVars} from '../theme/tokens.stylex';
+import {XDSField, type XDSInputStatus} from '../Field';
+import {XDSSizeProvider, useXDSSize} from '../SizeContext/XDSSizeContext';
+import {xdsClassName, mergeProps} from '../utils';
+import type {XDSBaseProps} from '../XDSBaseProps';
+import {XDSInputGroupContext} from './XDSInputGroupContext';
+
+export type XDSInputGroupSize = 'sm' | 'md' | 'lg';
+
+const styles = stylex.create({
+ group: {
+ display: 'inline-flex',
+ alignItems: 'stretch',
+ backgroundColor: 'transparent',
+ },
+ disabled: {
+ cursor: 'not-allowed',
+ opacity: 0.5,
+ },
+});
+
+const sizeStyles = stylex.create({
+ sm: {
+ height: sizeVars['--size-element-sm'],
+ },
+ md: {
+ height: sizeVars['--size-element-md'],
+ },
+ lg: {
+ height: sizeVars['--size-element-lg'],
+ },
+});
+
+export interface XDSInputGroupProps extends Omit<
+ XDSBaseProps<HTMLDivElement>,
+ 'children'
+> {
+ /** Ref forwarded to the group container element */
+ ref?: React.Ref<HTMLDivElement>;
+
+ /**
+ * Input and addon children.
+ */
+ children: ReactNode;
+
+ /**
+ * Label text for the group (required for accessibility).
+ */
+ label: string;
+
+ /**
+ * Whether to visually hide the label.
+ * @default false
+ */
+ isLabelHidden?: boolean;
+
+ /**
+ * Description text displayed between the label and input group.
+ */
+ description?: string;
+
+ /**
+ * Whether the group is disabled.
+ * @default false
+ */
+ isDisabled?: boolean;
+
+ /**
+ * Whether the field is optional.
+ * @default false
+ */
+ isOptional?: boolean;
+
+ /**
+ * Whether the field is required.
+ * @default false
+ */
+ isRequired?: boolean;
+
+ /**
+ * Default size for inputs in the group.
+ * @default 'md'
+ */
+ size?: XDSInputGroupSize;
+
+ /**
+ * Status indicator applied to the group border.
+ */
+ status?: XDSInputStatus;
+
+ /**
+ * Tooltip text at the end of the label.
+ */
+ labelTooltip?: string;
+
+ /**
+ * Test ID for testing frameworks.
+ */
+ 'data-testid'?: string;
+}
+
+/**
+ * Groups an input with prefix/suffix addons in a visually connected
+ * container with shared border and focus ring.
+ *
+ * @example
+ * ```
+ * <XDSInputGroup label="Price">
+ * <XDSInputGroupText>$</XDSInputGroupText>
+ * <XDSTextInput label="Price" isLabelHidden value={price} onChange={setPrice} />
+ * </XDSInputGroup>
+ * ```
+ */
+export function XDSInputGroup({
+ children,
+ label,
+ isLabelHidden = false,
+ description,
+ isDisabled = false,
+ isOptional = false,
+ isRequired = false,
+ size: sizeProp,
+ status,
+ labelTooltip,
+ xstyle,
+ className,
+ style,
+ ref,
+ 'data-testid': testId,
+ ...rest
+}: XDSInputGroupProps) {
+ const size = useXDSSize(sizeProp, 'md');
+ const inputId = useId();
+ const statusMessageId = useId();
+
+ const contextValue = useMemo(() => ({isInGroup: true as const}), []);
+
+ return (
+ <XDSInputGroupContext.Provider value={contextValue}>
+ <XDSSizeProvider value={size}>
+ <XDSField
+ label={label}
+ isLabelHidden={isLabelHidden}
+ description={description}
+ inputID={inputId}
+ isOptional={isOptional}
+ isRequired={isRequired}
+ isDisabled={isDisabled}
+ status={
+ status
+ ? {
+ type: status.type,
+ message: status.message,
+ messageID: status.message ? statusMessageId : undefined,
+ }
+ : undefined
+ }
+ statusVariant="detached"
+ labelTooltip={labelTooltip}>
+ <div
+ ref={ref}
+ role="group"
+ aria-label={label}
+ data-testid={testId}
+ {...rest}
+ {...mergeProps(
+ xdsClassName('input-group', {
+ size,
+ status: status?.type ?? null,
+ }),
+ stylex.props(
+ styles.group,
+ sizeStyles[size],
+ isDisabled && styles.disabled,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ {children}
+ </div>
+ </XDSField>
+ </XDSSizeProvider>
+ </XDSInputGroupContext.Provider>
+ );
+}
+
+XDSInputGroup.displayName = 'XDSInputGroup';
diff --git a/packages/core/src/InputGroup/XDSInputGroupContext.ts b/packages/core/src/InputGroup/XDSInputGroupContext.ts
new file mode 100644
index 0000000000..c03ea2d80c
--- /dev/null
+++ b/packages/core/src/InputGroup/XDSInputGroupContext.ts
@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file XDSInputGroupContext.ts
+ * @input None (pure context definition)
+ * @output Exports InputGroup context and useXDSInputGroup hook
+ * @position Shared context; consumed by input components for group-aware styling
+ */
+
+import {createContext, useContext} from 'react';
+
+export interface XDSInputGroupContextValue {
+ isInGroup: true;
+}
+
+export const XDSInputGroupContext =
+ createContext<XDSInputGroupContextValue | null>(null);
+
+/**
+ * Hook for input components to detect when inside an InputGroup.
+ * Returns null when used outside a group.
+ */
+export function useXDSInputGroup(): XDSInputGroupContextValue | null {
+ return useContext(XDSInputGroupContext);
+}
diff --git a/packages/core/src/InputGroup/XDSInputGroupText.tsx b/packages/core/src/InputGroup/XDSInputGroupText.tsx
new file mode 100644
index 0000000000..375e8fcf92
--- /dev/null
+++ b/packages/core/src/InputGroup/XDSInputGroupText.tsx
@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file XDSInputGroupText.tsx
+ * @input Uses React, StyleX, theme tokens
+ * @output Exports XDSInputGroupText component
+ * @position Text/icon element rendered inside XDSInputGroup
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/InputGroup/InputGroup.doc.mjs
+ * - /packages/core/src/InputGroup/index.ts
+ * - /packages/cli/templates/blocks/components/InputGroup/
+ */
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ typographyVars,
+ typeScaleVars,
+ borderVars,
+} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+
+const styles = stylex.create({
+ text: {
+ display: 'flex',
+ alignItems: 'center',
+ paddingInline: spacingVars['--spacing-2'],
+ backgroundColor: colorVars['--color-background-muted'],
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ color: colorVars['--color-text-secondary'],
+ whiteSpace: 'nowrap',
+ flexShrink: 0,
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-border-emphasized'],
+ marginInlineStart: {
+ default: `calc(-1 * ${borderVars['--border-width']})`,
+ ':first-child': 0,
+ },
+ borderStartStartRadius: {
+ default: 0,
+ ':first-child': radiusVars['--radius-element'],
+ },
+ borderEndStartRadius: {
+ default: 0,
+ ':first-child': radiusVars['--radius-element'],
+ },
+ borderStartEndRadius: {
+ default: 0,
+ ':last-child': radiusVars['--radius-element'],
+ },
+ borderEndEndRadius: {
+ default: 0,
+ ':last-child': radiusVars['--radius-element'],
+ },
+ },
+});
+
+export interface XDSInputGroupTextProps {
+ /**
+ * Content to render in the text slot.
+ * Can be text or an icon.
+ */
+ children: ReactNode;
+
+ /**
+ * StyleX styles for customization.
+ */
+ xstyle?: StyleXStyles;
+
+ /**
+ * CSS class name(s).
+ */
+ className?: string;
+
+ /**
+ * Inline styles.
+ */
+ style?: React.CSSProperties;
+}
+
+/**
+ * A prefix or suffix text element for use inside XDSInputGroup.
+ *
+ * @example
+ * ```
+ * <XDSInputGroup label="URL">
+ * <XDSInputGroupText>https://</XDSInputGroupText>
+ * <XDSTextInput label="URL" isLabelHidden value={url} onChange={setUrl} />
+ * </XDSInputGroup>
+ * ```
+ */
+export function XDSInputGroupText({
+ children,
+ xstyle,
+ className,
+ style,
+}: XDSInputGroupTextProps) {
+ return (
+ <div {...mergeProps(stylex.props(styles.text, xstyle), className, style)}>
+ {children}
+ </div>
+ );
+}
+
+XDSInputGroupText.displayName = 'XDSInputGroupText';
diff --git a/packages/core/src/InputGroup/groupStyles.ts b/packages/core/src/InputGroup/groupStyles.ts
new file mode 100644
index 0000000000..f165135523
--- /dev/null
+++ b/packages/core/src/InputGroup/groupStyles.ts
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file groupStyles.ts
+ * @input Uses StyleX, theme tokens
+ * @output Exports shared group-aware styles for input components
+ * @position Shared styles consumed by TextInput, NumberInput when inside an InputGroup
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {radiusVars, borderVars} from '../theme/tokens.stylex';
+
+export const groupStyles = stylex.create({
+ inGroup: {
+ flex: 1,
+ minWidth: 0,
+ height: '100%',
+ marginInlineStart: {
+ default: `calc(-1 * ${borderVars['--border-width']})`,
+ ':first-child': 0,
+ },
+ borderStartStartRadius: {
+ default: 0,
+ ':first-child': radiusVars['--radius-element'],
+ },
+ borderEndStartRadius: {
+ default: 0,
+ ':first-child': radiusVars['--radius-element'],
+ },
+ borderStartEndRadius: {
+ default: 0,
+ ':last-child': radiusVars['--radius-element'],
+ },
+ borderEndEndRadius: {
+ default: 0,
+ ':last-child': radiusVars['--radius-element'],
+ },
+ ':focus-within': {
+ zIndex: 1,
+ },
+ },
+});
diff --git a/packages/core/src/InputGroup/index.ts b/packages/core/src/InputGroup/index.ts
new file mode 100644
index 0000000000..af82f6b0b0
--- /dev/null
+++ b/packages/core/src/InputGroup/index.ts
@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from XDSInputGroup.tsx, XDSInputGroupText.tsx, XDSInputGroupContext.ts
+ * @output Exports XDSInputGroup, XDSInputGroupText, context hook, and types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ */
+
+export {XDSInputGroup} from './XDSInputGroup';
+export type {XDSInputGroupProps, XDSInputGroupSize} from './XDSInputGroup';
+
+export {XDSInputGroupText} from './XDSInputGroupText';
+export type {XDSInputGroupTextProps} from './XDSInputGroupText';
+
+export {useXDSInputGroup} from './XDSInputGroupContext';
diff --git a/packages/core/src/NumberInput/XDSNumberInput.tsx b/packages/core/src/NumberInput/XDSNumberInput.tsx
index 94a8c9f30b..17b96f64a0 100644
--- a/packages/core/src/NumberInput/XDSNumberInput.tsx
+++ b/packages/core/src/NumberInput/XDSNumberInput.tsx
@@ -48,6 +48,7 @@ import {
import {XDSIcon, renderIconSlot, type XDSIconType} from '../Icon';
import {useXDSSize} from '../SizeContext/XDSSizeContext';
import {useInputContainer} from '../hooks/useInputContainer';
+import {useXDSInputGroup} from '../InputGroup/XDSInputGroupContext';
const styles = stylex.create({
wrapper: {
@@ -119,6 +120,8 @@ const sizeStyles = stylex.create({
export type XDSNumberInputSize = keyof typeof sizeStyles;
+import {groupStyles} from '../InputGroup/groupStyles';
+
// Re-export shared types for convenience
export type {
@@ -368,6 +371,7 @@ export function XDSNumberInput({
const statusMessageID = useId();
const inputRef = useRef<HTMLInputElement | null>(null);
const containerRef = useRef<HTMLDivElement | null>(null);
+ const inputGroup = useXDSInputGroup();
// Pending input while user is typing (null = show formatted value)
const [pendingInput, setPendingInput] = useState<string | null>(null);
@@ -520,6 +524,81 @@ export function XDSNumberInput({
disabled: isDisabled,
});
+ const inputWrapper = (
+ <div
+ ref={containerRef}
+ onClick={handleWrapperClick}
+ onMouseUp={handleWrapperMouseUp}
+ {...mergeProps(
+ xdsClassName('number-input', {size, status: status?.type ?? null}),
+ stylex.props(
+ inputWrapperStyles.base,
+ styles.wrapper,
+ sizeStyles[size],
+ isDisabled && inputWrapperStyles.disabled,
+ status && inputStatusBorderStyles[status.type],
+ status && inputStatusHoverShadowStyles[status.type],
+ status && inputStatusFocusWithinStyles[status.type],
+ inputGroup && groupStyles.inGroup,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ {startIcon && renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+ <input
+ {...rest}
+ ref={setRefs}
+ id={id}
+ name={htmlName}
+ type="number"
+ autoComplete={autoComplete}
+ value={displayValue}
+ onChange={handleInputChange}
+ onFocus={handleFocus}
+ onBlur={handleBlur}
+ onKeyDown={handleKeyDown}
+ placeholder={placeholder}
+ disabled={isDisabled}
+ autoFocus={hasAutoFocus}
+ data-autofocus={hasAutoFocus || undefined}
+ min={min ?? undefined}
+ max={max ?? undefined}
+ step={step ?? undefined}
+ aria-describedby={ariaDescribedBy}
+ aria-required={isRequired === true ? 'true' : undefined}
+ aria-invalid={status?.type === 'error' ? 'true' : undefined}
+ aria-label={inputGroup ? label : undefined}
+ {...stylex.props(
+ styles.input,
+ isDisabled && styles.inputDisabled,
+ !isInputValid && styles.inputInvalid,
+ )}
+ />
+ {units && <span {...stylex.props(styles.units)}>{units}</span>}
+ {hasClear && value != null && !isDisabled && (
+ <button
+ type="button"
+ onClick={handleClear}
+ aria-label={`Clear ${label}`}
+ {...stylex.props(styles.clearButton)}>
+ <XDSIcon icon="close" size="sm" color="secondary" />
+ </button>
+ )}
+ {status && !inputGroup && (
+ <XDSIcon
+ icon={statusIconMap[status.type]}
+ size="md"
+ color={statusIconColorMap[status.type]}
+ />
+ )}
+ </div>
+ );
+
+ if (inputGroup) {
+ return inputWrapper;
+ }
+
return (
<XDSField
label={label}
@@ -541,73 +620,7 @@ export function XDSNumberInput({
: undefined
}
labelTooltip={labelTooltip}>
- <div
- ref={containerRef}
- onClick={handleWrapperClick}
- onMouseUp={handleWrapperMouseUp}
- {...mergeProps(
- xdsClassName('number-input', {size, status: status?.type ?? null}),
- stylex.props(
- inputWrapperStyles.base,
- styles.wrapper,
- sizeStyles[size],
- isDisabled && inputWrapperStyles.disabled,
- status && inputStatusBorderStyles[status.type],
- status && inputStatusHoverShadowStyles[status.type],
- status && inputStatusFocusWithinStyles[status.type],
- xstyle,
- ),
- className,
- style,
- )}>
- {startIcon &&
- renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
- <input
- {...rest}
- ref={setRefs}
- id={id}
- name={htmlName}
- type="number"
- autoComplete={autoComplete}
- value={displayValue}
- onChange={handleInputChange}
- onFocus={handleFocus}
- onBlur={handleBlur}
- onKeyDown={handleKeyDown}
- placeholder={placeholder}
- disabled={isDisabled}
- autoFocus={hasAutoFocus}
- data-autofocus={hasAutoFocus || undefined}
- min={min ?? undefined}
- max={max ?? undefined}
- step={step ?? undefined}
- aria-describedby={ariaDescribedBy}
- aria-required={isRequired === true ? 'true' : undefined}
- aria-invalid={status?.type === 'error' ? 'true' : undefined}
- {...stylex.props(
- styles.input,
- isDisabled && styles.inputDisabled,
- !isInputValid && styles.inputInvalid,
- )}
- />
- {units && <span {...stylex.props(styles.units)}>{units}</span>}
- {hasClear && value != null && !isDisabled && (
- <button
- type="button"
- onClick={handleClear}
- aria-label={`Clear ${label}`}
- {...stylex.props(styles.clearButton)}>
- <XDSIcon icon="close" size="sm" color="secondary" />
- </button>
- )}
- {status && (
- <XDSIcon
- icon={statusIconMap[status.type]}
- size="md"
- color={statusIconColorMap[status.type]}
- />
- )}
- </div>
+ {inputWrapper}
</XDSField>
);
}
diff --git a/packages/core/src/TextInput/XDSTextInput.tsx b/packages/core/src/TextInput/XDSTextInput.tsx
index 2738b1b543..113a2bb7f7 100644
--- a/packages/core/src/TextInput/XDSTextInput.tsx
+++ b/packages/core/src/TextInput/XDSTextInput.tsx
@@ -105,6 +105,8 @@ const sizeStyles = stylex.create({
export type XDSTextInputSize = keyof typeof sizeStyles;
+import {groupStyles} from '../InputGroup/groupStyles';
+
// Re-export shared types for convenience
export type {
@@ -114,6 +116,7 @@ export type {
import {xdsClassName, mergeProps} from '../utils';
import {useXDSSize} from '../SizeContext/XDSSizeContext';
import {useInputContainer} from '../hooks/useInputContainer';
+import {useXDSInputGroup} from '../InputGroup/XDSInputGroupContext';
import {XDSBaseProps} from '../XDSBaseProps';
export type XDSTextInputType = 'text' | 'password' | 'email';
@@ -268,6 +271,7 @@ export function XDSTextInput({
const statusMessageID = useId();
const inputRef = useRef<HTMLInputElement | null>(null);
const containerRef = useRef<HTMLDivElement | null>(null);
+ const inputGroup = useXDSInputGroup();
const [, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -334,6 +338,80 @@ export function XDSTextInput({
disabled: isDisabled,
});
+ const inputWrapper = (
+ <div
+ ref={containerRef}
+ onClick={handleWrapperClick}
+ onMouseUp={handleWrapperMouseUp}
+ {...mergeProps(
+ xdsClassName('text-input', {size, status: status?.type ?? null}),
+ stylex.props(
+ inputWrapperStyles.base,
+ sizeStyles[size],
+ isDisabled && inputWrapperStyles.disabled,
+ status && inputStatusBorderStyles[status.type],
+ status && inputStatusHoverShadowStyles[status.type],
+ status && inputStatusFocusWithinStyles[status.type],
+ inputGroup && groupStyles.inGroup,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ {startIcon && renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+ <input
+ {...rest}
+ ref={setRefs}
+ id={id}
+ name={htmlName}
+ type={type}
+ value={String(optimisticValue)}
+ onChange={handleChange}
+ onKeyDown={
+ onEnter || onKeyDown
+ ? e => {
+ if (e.key === 'Enter') {
+ onEnter?.();
+ }
+ onKeyDown?.(e);
+ }
+ : undefined
+ }
+ placeholder={placeholder}
+ disabled={isDisabled}
+ autoFocus={hasAutoFocus}
+ data-autofocus={hasAutoFocus || undefined}
+ aria-describedby={ariaDescribedBy}
+ aria-required={isRequired === true ? 'true' : undefined}
+ aria-invalid={status?.type === 'error' ? 'true' : undefined}
+ aria-busy={isBusy || undefined}
+ aria-label={inputGroup ? label : undefined}
+ {...stylex.props(styles.input, isDisabled && styles.inputDisabled)}
+ />
+ {hasClear && value !== '' && !isDisabled && (
+ <button
+ type="button"
+ onClick={handleClear}
+ aria-label={`Clear ${label}`}
+ {...stylex.props(styles.clearButton)}>
+ <XDSIcon icon="close" size="sm" color="secondary" />
+ </button>
+ )}
+ {isBusy && <XDSSpinner size="sm" />}
+ {status && !inputGroup && (
+ <XDSIcon
+ icon={statusIconMap[status.type]}
+ size="md"
+ color={statusIconColorMap[status.type]}
+ />
+ )}
+ </div>
+ );
+
+ if (inputGroup) {
+ return inputWrapper;
+ }
+
return (
<XDSField
label={label}
@@ -354,72 +432,7 @@ export function XDSTextInput({
: undefined
}
labelTooltip={labelTooltip}>
- <div
- ref={containerRef}
- onClick={handleWrapperClick}
- onMouseUp={handleWrapperMouseUp}
- {...mergeProps(
- xdsClassName('text-input', {size, status: status?.type ?? null}),
- stylex.props(
- inputWrapperStyles.base,
- sizeStyles[size],
- isDisabled && inputWrapperStyles.disabled,
- status && inputStatusBorderStyles[status.type],
- status && inputStatusHoverShadowStyles[status.type],
- status && inputStatusFocusWithinStyles[status.type],
- xstyle,
- ),
- className,
- style,
- )}>
- {startIcon &&
- renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
- <input
- {...rest}
- ref={setRefs}
- id={id}
- name={htmlName}
- type={type}
- value={String(optimisticValue)}
- onChange={handleChange}
- onKeyDown={
- onEnter || onKeyDown
- ? e => {
- if (e.key === 'Enter') {
- onEnter?.();
- }
- onKeyDown?.(e);
- }
- : undefined
- }
- placeholder={placeholder}
- disabled={isDisabled}
- autoFocus={hasAutoFocus}
- data-autofocus={hasAutoFocus || undefined}
- aria-describedby={ariaDescribedBy}
- aria-required={isRequired === true ? 'true' : undefined}
- aria-invalid={status?.type === 'error' ? 'true' : undefined}
- aria-busy={isBusy || undefined}
- {...stylex.props(styles.input, isDisabled && styles.inputDisabled)}
- />
- {hasClear && value !== '' && !isDisabled && (
- <button
- type="button"
- onClick={handleClear}
- aria-label={`Clear ${label}`}
- {...stylex.props(styles.clearButton)}>
- <XDSIcon icon="close" size="sm" color="secondary" />
- </button>
- )}
- {isBusy && <XDSSpinner size="sm" />}
- {status && (
- <XDSIcon
- icon={statusIconMap[status.type]}
- size="md"
- color={statusIconColorMap[status.type]}
- />
- )}
- </div>
+ {inputWrapper}
</XDSField>
);
}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 6e6fa28244..5f7a3c10d1 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -64,6 +64,7 @@ export * from './SelectableCard';
export * from './Selector';
export * from './MultiSelector';
export * from './Icon';
+export * from './InputGroup';
export * from './Text';
export * from './TextInput';
export * from './TabList';