Skip to content

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

TypeScript

feat(input): add isReadOnly to TextInput, TextArea, NumberInput (#4816)

Joeyd56973f5069f
diff --git a/.changeset/readonly-text-inputs.md b/.changeset/readonly-text-inputs.md
new file mode 100644
index 0000000000..5a8e7bbfd6
--- /dev/null
+++ b/.changeset/readonly-text-inputs.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] TextInput, TextArea, NumberInput: add `isReadOnly`. The value is shown at full opacity and still submits with the form, but cannot be edited — the "visible, locked, still sent" case that `isDisabled` deliberately does not cover, since disabled controls are excluded from submission. Read-only fields are not dimmed and stay in the tab order, matching the native `readonly` semantics they compile to; `isDisabled` takes precedence when both are set, and the clear button is hidden while read-only. The state is reflected on the root theming target as `data-readonly="readonly"`, alongside the existing `data-disabled`, so a theme can paint it without structural `:has(input:read-only)` CSS. `isReadOnly` already existed on CheckboxInput, CheckboxList, and PowerSearch; the remaining text-ish inputs (DateInput, DateRangeInput, DateTimeInput, TimeInput, Tokenizer) do not have it yet.
+@josephfarina
diff --git a/apps/storybook/stories/NumberInput.stories.tsx b/apps/storybook/stories/NumberInput.stories.tsx
index ca16963aba..1354265b5e 100644
--- a/apps/storybook/stories/NumberInput.stories.tsx
+++ b/apps/storybook/stories/NumberInput.stories.tsx
@@ -50,6 +50,11 @@ const meta: Meta<typeof NumberInput> = {
control: 'boolean',
description: 'Whether the input is disabled',
},
+ isReadOnly: {
+ control: 'boolean',
+ description:
+ 'Whether the input is read-only. The value still submits with the form but cannot be edited. Unlike isDisabled it is not dimmed and stays in the tab order.',
+ },
disabledMessage: {
control: 'text',
description:
@@ -302,6 +307,20 @@ export const RequiredField: Story = {
},
};
+// Read-only shows a value the user should see and send but not change. Unlike
+// a disabled field it is not dimmed, stays in the tab order, and still submits.
+export const ReadOnly: Story = {
+ render: args => {
+ const [value, setValue] = useState<number | null>(args.value ?? 1024);
+ return <NumberInput {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Allocated storage (GB)',
+ isReadOnly: true,
+ value: 1024,
+ },
+};
+
export const Disabled: Story = {
render: args => {
const [value, setValue] = useState<number | null>(args.value ?? 100);
@@ -561,7 +580,8 @@ export const StatusVariantComparison: Story = {
const [a, setA] = useState<number | null>(-5);
const [b, setB] = useState<number | null>(-5);
return (
- <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 280}}>
+ <div
+ style={{display: 'flex', flexDirection: 'column', gap: 24, width: 280}}>
<NumberInput
label="Attached (default)"
value={a}
diff --git a/apps/storybook/stories/TextArea.stories.tsx b/apps/storybook/stories/TextArea.stories.tsx
index d3932bc3c5..22eb2f4628 100644
--- a/apps/storybook/stories/TextArea.stories.tsx
+++ b/apps/storybook/stories/TextArea.stories.tsx
@@ -56,6 +56,11 @@ const meta: Meta<typeof TextArea> = {
control: 'boolean',
description: 'Whether the textarea is disabled',
},
+ isReadOnly: {
+ control: 'boolean',
+ description:
+ 'Whether the textarea is read-only. The value still submits with the form but cannot be edited. Unlike isDisabled it is not dimmed and stays in the tab order.',
+ },
disabledMessage: {
control: 'text',
description:
@@ -270,6 +275,23 @@ export const DescriptionWithOptional: Story = {
},
};
+// Read-only shows a value the user should see and send but not change. Unlike
+// a disabled field it is not dimmed, stays in the tab order, and still submits.
+export const ReadOnly: Story = {
+ render: args => {
+ const [value, setValue] = useState(
+ args.value ??
+ 'Generated by the importer; edit the source file to change it.',
+ );
+ return <TextArea {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Import summary',
+ isReadOnly: true,
+ value: 'Generated by the importer; edit the source file to change it.',
+ },
+};
+
export const Disabled: Story = {
render: args => {
const [value, setValue] = useState(
diff --git a/apps/storybook/stories/TextInput.stories.tsx b/apps/storybook/stories/TextInput.stories.tsx
index 4040c53950..bb972733ab 100644
--- a/apps/storybook/stories/TextInput.stories.tsx
+++ b/apps/storybook/stories/TextInput.stories.tsx
@@ -54,6 +54,11 @@ const meta: Meta<typeof TextInput> = {
control: 'boolean',
description: 'Whether the input is disabled',
},
+ isReadOnly: {
+ control: 'boolean',
+ description:
+ 'Whether the input is read-only. The value still submits with the form but cannot be edited. Unlike isDisabled it is not dimmed and stays in the tab order.',
+ },
disabledMessage: {
control: 'text',
description:
@@ -230,6 +235,20 @@ export const DescriptionWithOptional: Story = {
},
};
+// Read-only shows a value the user should see and send but not change. Unlike
+// a disabled field it is not dimmed, stays in the tab order, and still submits.
+export const ReadOnly: Story = {
+ render: args => {
+ const [value, setValue] = useState(args.value ?? 'ACCT-4417-9920');
+ return <TextInput {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Account number',
+ isReadOnly: true,
+ value: 'ACCT-4417-9920',
+ },
+};
+
export const Disabled: Story = {
render: args => {
const [value, setValue] = useState(args.value ?? 'Cannot edit this');
diff --git a/packages/cli/assets/templates/blocks/components/TextArea/TextAreaStates.tsx b/packages/cli/assets/templates/blocks/components/TextArea/TextAreaStates.tsx
index a17a5c9028..2e66adfee2 100644
--- a/packages/cli/assets/templates/blocks/components/TextArea/TextAreaStates.tsx
+++ b/packages/cli/assets/templates/blocks/components/TextArea/TextAreaStates.tsx
@@ -20,7 +20,7 @@ export default function TextAreaStates() {
/>
<TextArea
label="Disabled field"
- value="This field is read-only and cannot be edited."
+ value="This field is disabled and cannot be edited."
onChange={() => {}}
isDisabled
/>
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
index f6bf4e1d94..325beebf9b 100644
--- a/packages/core/src/NumberInput/NumberInput.doc.mjs
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -62,6 +62,13 @@ export const docs = {
type: 'boolean',
description: 'Whether the input is disabled.',
},
+ {
+ name: 'isReadOnly',
+ type: 'boolean',
+ description:
+ 'Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and stays in the tab order. isDisabled takes precedence when both are set.',
+ default: 'false',
+ },
{
name: 'disabledMessage',
type: 'string',
@@ -174,7 +181,7 @@ export const docs = {
],
theming: {
targets: [
- {className: 'astryx-number-input', visualProps: ['size', 'status'], states: ['disabled']},
+ {className: 'astryx-number-input', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
],
},
usage: {
@@ -255,6 +262,13 @@ export const docsZh = {
type: 'boolean',
description: '输入框是否禁用。',
},
+ {
+ name: 'isReadOnly',
+ type: 'boolean',
+ description:
+ '将输入框设为只读:值以完整不透明度显示并仍随表单提交,但无法编辑。与 isDisabled 不同,只读输入框不会变暗,并保留在 Tab 顺序中。同时设置时 isDisabled 优先。',
+ default: 'false',
+ },
{
name: 'disabledMessage',
type: 'string',
@@ -360,7 +374,7 @@ export const docsZh = {
],
theming: {
targets: [
- {className: 'astryx-number-input', visualProps: ['size', 'status'], states: ['disabled']},
+ {className: 'astryx-number-input', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
],
},
usage: {
@@ -412,6 +426,8 @@ export const docsDense = {
isOptional: 'Field optional (mutually exclusive w/ isRequired).',
isRequired: 'Field required (mutually exclusive w/ isOptional).',
isDisabled: 'Input disabled.',
+ isReadOnly:
+ 'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed, stays in tab order.',
disabledMessage:
'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps input focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled NumberInput in Tooltip.',
placeholder: 'Placeholder text.',
diff --git a/packages/core/src/NumberInput/NumberInput.test.tsx b/packages/core/src/NumberInput/NumberInput.test.tsx
index e16e39a9f0..91a8f83e35 100644
--- a/packages/core/src/NumberInput/NumberInput.test.tsx
+++ b/packages/core/src/NumberInput/NumberInput.test.tsx
@@ -742,6 +742,100 @@ describe('NumberInput', () => {
});
});
+ describe('isReadOnly', () => {
+ it('marks the input read-only', () => {
+ render(
+ <NumberInput
+ label="Quantity"
+ value={42}
+ onChange={() => {}}
+ isReadOnly
+ />,
+ );
+ expect(screen.getByRole('spinbutton')).toHaveAttribute('readonly');
+ });
+
+ it('still submits its value with the form', () => {
+ const {container} = render(
+ <form>
+ <NumberInput
+ label="Quantity"
+ htmlName="quantity"
+ value={42}
+ onChange={() => {}}
+ isReadOnly
+ />
+ </form>,
+ );
+ expect(
+ new FormData(container.querySelector('form')!).get('quantity'),
+ ).toBe('42');
+ });
+
+ it('does not call onChange when the user types', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+ render(
+ <NumberInput
+ label="Quantity"
+ value={42}
+ onChange={handleChange}
+ isReadOnly
+ />,
+ );
+ await user.type(screen.getByRole('spinbutton'), '7');
+ expect(handleChange).not.toHaveBeenCalled();
+ });
+
+ it('stays focusable and is not disabled', async () => {
+ const user = userEvent.setup();
+ render(
+ <NumberInput
+ label="Quantity"
+ value={42}
+ onChange={() => {}}
+ isReadOnly
+ />,
+ );
+ const input = screen.getByRole('spinbutton');
+ expect(input).not.toBeDisabled();
+ await user.tab();
+ expect(input).toHaveFocus();
+ });
+
+ it('hides the clear button', () => {
+ render(
+ <NumberInput
+ label="Quantity"
+ value={42}
+ onChange={() => {}}
+ hasClear
+ isReadOnly
+ />,
+ );
+ expect(screen.queryByRole('button')).not.toBeInTheDocument();
+ });
+
+ it('lets isDisabled win when both are set', () => {
+ const {container} = render(
+ <form>
+ <NumberInput
+ label="Quantity"
+ htmlName="quantity"
+ value={42}
+ onChange={() => {}}
+ isReadOnly
+ isDisabled
+ />
+ </form>,
+ );
+ expect(screen.getByRole('spinbutton')).toBeDisabled();
+ expect([
+ ...new FormData(container.querySelector('form')!).keys(),
+ ]).toEqual([]);
+ });
+ });
+
describe('autoComplete prop', () => {
it('sets autocomplete attribute when autoComplete is provided', () => {
render(
@@ -1101,3 +1195,21 @@ describe('NumberInput disabled theme state', () => {
expect(root).not.toHaveAttribute('data-disabled');
});
});
+
+describe('NumberInput readonly theme state', () => {
+ it('reflects readonly on the root target so themes can gate paint on it', () => {
+ const {container} = render(
+ <NumberInput label="Qty" value={1} onChange={() => {}} isReadOnly />,
+ );
+ const root = container.querySelector('.astryx-number-input');
+ expect(root).toHaveAttribute('data-readonly', 'readonly');
+ });
+
+ it('omits data-readonly when editable', () => {
+ const {container} = render(
+ <NumberInput label="Qty" value={1} onChange={() => {}} />,
+ );
+ const root = container.querySelector('.astryx-number-input');
+ expect(root).not.toHaveAttribute('data-readonly');
+ });
+});
diff --git a/packages/core/src/NumberInput/NumberInput.tsx b/packages/core/src/NumberInput/NumberInput.tsx
index 69dbf1b579..b0152f63f6 100644
--- a/packages/core/src/NumberInput/NumberInput.tsx
+++ b/packages/core/src/NumberInput/NumberInput.tsx
@@ -183,6 +183,15 @@ interface NumberInputPropsBase extends Omit<
* @default false
*/
isDisabled?: boolean;
+ /**
+ * Whether the input is read-only.
+ * The value is shown at full opacity and still submits with the form, but
+ * cannot be edited. Unlike `isDisabled`, a read-only input is not dimmed and
+ * stays in the tab order — use it for a value the user should see and send
+ * but not change. `isDisabled` takes precedence when both are set.
+ * @default false
+ */
+ isReadOnly?: boolean;
/**
* Explains why the input is disabled. When set together with `isDisabled`,
* the input shows a tooltip with this text on hover and keyboard focus, and
@@ -390,6 +399,7 @@ export function NumberInput({
isOptional = false,
isRequired = false,
isDisabled = false,
+ isReadOnly = false,
disabledMessage,
startIcon,
labelIcon,
@@ -499,7 +509,7 @@ export function NumberInput({
// Value can't change while showing a disabled message (the field is
// read-only and non-native-disabled), but guard the handler too so the
// pending value and onChange never fire.
- if (isDisabled) {
+ if (isDisabled || isReadOnly) {
return;
}
const newValue = e.target.value;
@@ -511,7 +521,7 @@ export function NumberInput({
onChange(parsed);
}
},
- [value, onChange, min, max, isIntegerOnly, isDisabled],
+ [value, onChange, min, max, isIntegerOnly, isDisabled, isReadOnly],
);
// Handle focus
@@ -634,6 +644,7 @@ export function NumberInput({
size,
status: status?.type ?? null,
disabled: isDisabled ? 'disabled' : null,
+ readonly: isReadOnly ? 'readonly' : null,
}),
stylex.props(
inputWrapperStyles.base,
@@ -670,7 +681,7 @@ export function NumberInput({
// keep the value from changing.
disabled={isDisabled && !showsDisabledMessage}
aria-disabled={showsDisabledMessage ? 'true' : undefined}
- readOnly={showsDisabledMessage || undefined}
+ readOnly={isReadOnly || showsDisabledMessage || undefined}
autoFocus={hasAutoFocus}
data-autofocus={hasAutoFocus || undefined}
min={min ?? undefined}
@@ -701,7 +712,7 @@ export function NumberInput({
<VisuallyHidden as="div" role="alert" aria-live="assertive">
{!isInputValid ? 'Invalid number' : ''}
</VisuallyHidden>
- {hasClear && value != null && !isDisabled && (
+ {hasClear && value != null && !isDisabled && !isReadOnly && (
<button
type="button"
onClick={handleClear}
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index b4931d9591..9297211a89 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -70,6 +70,13 @@ export const docs = {
description: 'Disables the textarea, preventing interaction.',
default: 'false',
},
+ {
+ name: 'isReadOnly',
+ type: 'boolean',
+ description:
+ 'Makes the textarea read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only textarea is not dimmed and stays in the tab order. isDisabled takes precedence when both are set.',
+ default: 'false',
+ },
{
name: 'disabledMessage',
type: 'string',
@@ -179,7 +186,7 @@ export const docs = {
],
theming: {
targets: [
- {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled']},
+ {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
],
vars: [
{
@@ -271,6 +278,13 @@ export const docsZh = {
description: '禁用文本域,阻止交互。',
default: 'false',
},
+ {
+ name: 'isReadOnly',
+ type: 'boolean',
+ description:
+ '将文本域设为只读:值以完整不透明度显示并仍随表单提交,但无法编辑。与 isDisabled 不同,只读文本域不会变暗,并保留在 Tab 顺序中。同时设置时 isDisabled 优先。',
+ default: 'false',
+ },
{
name: 'disabledMessage',
type: 'string',
@@ -367,7 +381,7 @@ export const docsZh = {
],
theming: {
targets: [
- {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled']},
+ {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
],
vars: [
{
@@ -426,6 +440,8 @@ export const docsDense = {
isOptional: 'Shows "Optional" indicator. Mutually exclusive w/ isRequired.',
isRequired: 'Shows "Required" indicator+sets aria-required. Mutually exclusive w/ isOptional.',
isDisabled: 'Disables textarea, prevents interaction.',
+ isReadOnly:
+ 'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed, stays in tab order.',
disabledMessage:
'Explains why textarea is disabled. With isDisabled, shows tooltip on hover/focus + keeps textarea focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled TextArea in Tooltip.',
isLoading: 'Loading state w/ spinner inside input.',
diff --git a/packages/core/src/TextArea/TextArea.test.tsx b/packages/core/src/TextArea/TextArea.test.tsx
index 16eba3cea3..efaf66d874 100644
--- a/packages/core/src/TextArea/TextArea.test.tsx
+++ b/packages/core/src/TextArea/TextArea.test.tsx
@@ -728,6 +728,77 @@ describe('TextArea', () => {
});
});
+ describe('isReadOnly', () => {
+ it('marks the textarea read-only', () => {
+ render(
+ <TextArea label="Notes" value="hello" onChange={() => {}} isReadOnly />,
+ );
+ expect(screen.getByRole('textbox')).toHaveAttribute('readonly');
+ });
+
+ it('still submits its value with the form', () => {
+ const {container} = render(
+ <form>
+ <TextArea
+ label="Notes"
+ htmlName="notes"
+ value="hello"
+ onChange={() => {}}
+ isReadOnly
+ />
+ </form>,
+ );
+ expect(new FormData(container.querySelector('form')!).get('notes')).toBe(
+ 'hello',
+ );
+ });
+
+ it('does not call onChange when the user types', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+ render(
+ <TextArea
+ label="Notes"
+ value="hello"
+ onChange={handleChange}
+ isReadOnly
+ />,
+ );
+ await user.type(screen.getByRole('textbox'), 'xyz');
+ expect(handleChange).not.toHaveBeenCalled();
+ });
+
+ it('stays focusable and is not disabled', async () => {
+ const user = userEvent.setup();
+ render(
+ <TextArea label="Notes" value="hello" onChange={() => {}} isReadOnly />,
+ );
+ const textarea = screen.getByRole('textbox');
+ expect(textarea).not.toBeDisabled();
+ await user.tab();
+ expect(textarea).toHaveFocus();
+ });
+
+ it('lets isDisabled win when both are set', () => {
+ const {container} = render(
+ <form>
+ <TextArea
+ label="Notes"
+ htmlName="notes"
+ value="hello"
+ onChange={() => {}}
+ isReadOnly
+ isDisabled
+ />
+ </form>,
+ );
+ expect(screen.getByRole('textbox')).toBeDisabled();
+ expect([
+ ...new FormData(container.querySelector('form')!).keys(),
+ ]).toEqual([]);
+ });
+ });
+
describe('click-to-focus', () => {
it('focuses textarea when clicking the start icon', () => {
render(
@@ -938,3 +1009,21 @@ describe('TextArea disabled theme state', () => {
expect(root).not.toHaveAttribute('data-disabled');
});
});
+
+describe('TextArea readonly theme state', () => {
+ it('reflects readonly on the root target so themes can gate paint on it', () => {
+ const {container} = render(
+ <TextArea label="Notes" value="" onChange={() => {}} isReadOnly />,
+ );
+ const root = container.querySelector('.astryx-textarea');
+ expect(root).toHaveAttribute('data-readonly', 'readonly');
+ });
+
+ it('omits data-readonly when editable', () => {
+ const {container} = render(
+ <TextArea label="Notes" value="" onChange={() => {}} />,
+ );
+ const root = container.querySelector('.astryx-textarea');
+ expect(root).not.toHaveAttribute('data-readonly');
+ });
+});
diff --git a/packages/core/src/TextArea/TextArea.tsx b/packages/core/src/TextArea/TextArea.tsx
index 87fdcd5b96..cb7fa7bc1b 100644
--- a/packages/core/src/TextArea/TextArea.tsx
+++ b/packages/core/src/TextArea/TextArea.tsx
@@ -243,6 +243,15 @@ export interface TextAreaProps extends Omit<
* @default false
*/
isDisabled?: boolean;
+ /**
+ * Whether the textarea is read-only.
+ * The value is shown at full opacity and still submits with the form, but
+ * cannot be edited. Unlike `isDisabled`, a read-only textarea is not dimmed
+ * and stays in the tab order — use it for a value the user should see and
+ * send but not change. `isDisabled` takes precedence when both are set.
+ * @default false
+ */
+ isReadOnly?: boolean;
/**
* Explains why the textarea is disabled. When set together with
* `isDisabled`, the textarea shows a tooltip with this text on hover and
@@ -357,6 +366,7 @@ export function TextArea({
placeholder,
rows = 3,
isDisabled = false,
+ isReadOnly = false,
disabledMessage,
status,
statusVariant = 'attached',
@@ -468,7 +478,7 @@ export function TextArea({
// Value can't change while showing a disabled message (the field is
// read-only and non-native-disabled), but guard the handler too so the
// optimistic value and callbacks never fire.
- if (isDisabled) {
+ if (isDisabled || isReadOnly) {
return;
}
const newValue = e.target.value;
@@ -529,6 +539,7 @@ export function TextArea({
size,
status: status?.type ?? null,
disabled: isDisabled ? 'disabled' : null,
+ readonly: isReadOnly ? 'readonly' : null,
}),
stylex.props(
inputWrapperStyles.base,
@@ -564,7 +575,7 @@ export function TextArea({
// handleChange guard keep the value from changing.
disabled={isDisabled && !showsDisabledMessage}
aria-disabled={showsDisabledMessage ? 'true' : undefined}
- readOnly={showsDisabledMessage || undefined}
+ readOnly={isReadOnly || showsDisabledMessage || undefined}
spellCheck={hasSpellCheck}
autoFocus={hasAutoFocus}
data-autofocus={hasAutoFocus || undefined}
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index 9e8168182d..08757daa46 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -78,6 +78,13 @@ export const docs = {
'Disables the input, preventing interaction and dimming the element.',
default: 'false',
},
+ {
+ name: 'isReadOnly',
+ type: 'boolean',
+ description:
+ 'Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and stays in the tab order. isDisabled takes precedence when both are set.',
+ default: 'false',
+ },
{
name: 'disabledMessage',
type: 'string',
@@ -149,7 +156,7 @@ export const docs = {
],
theming: {
targets: [
- {className: 'astryx-text-input', visualProps: ['size', 'status'], states: ['disabled']},
+ {className: 'astryx-text-input', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
],
},
usage: {
@@ -251,6 +258,13 @@ export const docsZh = {
'禁用输入框,阻止交互并使元素变暗。',
default: 'false',
},
+ {
+ name: 'isReadOnly',
+ type: 'boolean',
+ description:
+ '将输入框设为只读:值以完整不透明度显示并仍随表单提交,但无法编辑。与 isDisabled 不同,只读输入框不会变暗,并保留在 Tab 顺序中。同时设置时 isDisabled 优先。',
+ default: 'false',
+ },
{
name: 'disabledMessage',
type: 'string',
@@ -315,7 +329,7 @@ export const docsZh = {
],
theming: {
targets: [
- {className: 'astryx-text-input', visualProps: ['size', 'status'], states: ['disabled']},
+ {className: 'astryx-text-input', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
],
},
usage: {
@@ -381,6 +395,8 @@ export const docsDense = {
isOptional: 'Shows "Optional" indicator. Mutually exclusive w/ isRequired.',
isRequired: 'Shows "Required" indicator+sets aria-required. Mutually exclusive w/ isOptional.',
isDisabled: 'Disables input, prevents interaction, dims element.',
+ isReadOnly:
+ 'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed, stays in tab order.',
disabledMessage:
'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps input focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled TextInput in Tooltip.',
isLoading: 'Loading state w/ spinner+aria-busy.',
diff --git a/packages/core/src/TextInput/TextInput.test.tsx b/packages/core/src/TextInput/TextInput.test.tsx
index 22f36e362b..4ff1a9c1b0 100644
--- a/packages/core/src/TextInput/TextInput.test.tsx
+++ b/packages/core/src/TextInput/TextInput.test.tsx
@@ -426,6 +426,100 @@ describe('TextInput', () => {
});
});
+ describe('isReadOnly', () => {
+ it('marks the input read-only', () => {
+ render(
+ <TextInput
+ label="Owner"
+ value="alice"
+ onChange={() => {}}
+ isReadOnly
+ />,
+ );
+ expect(screen.getByRole('textbox')).toHaveAttribute('readonly');
+ });
+
+ it('still submits its value with the form', () => {
+ const {container} = render(
+ <form>
+ <TextInput
+ label="Owner"
+ htmlName="owner"
+ value="alice"
+ onChange={() => {}}
+ isReadOnly
+ />
+ </form>,
+ );
+ expect(new FormData(container.querySelector('form')!).get('owner')).toBe(
+ 'alice',
+ );
+ });
+
+ it('does not call onChange when the user types', async () => {
+ const user = userEvent.setup();
+ const handleChange = vi.fn();
+ render(
+ <TextInput
+ label="Owner"
+ value="alice"
+ onChange={handleChange}
+ isReadOnly
+ />,
+ );
+ await user.type(screen.getByRole('textbox'), 'xyz');
+ expect(handleChange).not.toHaveBeenCalled();
+ });
+
+ it('stays focusable and is not disabled', async () => {
+ const user = userEvent.setup();
+ render(
+ <TextInput
+ label="Owner"
+ value="alice"
+ onChange={() => {}}
+ isReadOnly
+ />,
+ );
+ const input = screen.getByRole('textbox');
+ expect(input).not.toBeDisabled();
+ await user.tab();
+ expect(input).toHaveFocus();
+ });
+
+ it('hides the clear button', () => {
+ render(
+ <TextInput
+ label="Owner"
+ value="alice"
+ onChange={() => {}}
+ hasClear
+ isReadOnly
+ />,
+ );
+ expect(screen.queryByRole('button')).not.toBeInTheDocument();
+ });
+
+ it('lets isDisabled win when both are set', () => {
+ const {container} = render(
+ <form>
+ <TextInput
+ label="Owner"
+ htmlName="owner"
+ value="alice"
+ onChange={() => {}}
+ isReadOnly
+ isDisabled
+ />
+ </form>,
+ );
+ expect(screen.getByRole('textbox')).toBeDisabled();
+ expect([
+ ...new FormData(container.querySelector('form')!).keys(),
+ ]).toEqual([]);
+ });
+ });
+
describe('onEnter', () => {
it('calls onEnter when Enter key is pressed', async () => {
const user = userEvent.setup();
@@ -886,3 +980,21 @@ describe('TextInput disabled theme state', () => {
expect(root).not.toHaveAttribute('data-disabled');
});
});
+
+describe('TextInput readonly theme state', () => {
+ it('reflects readonly on the root target so themes can gate paint on it', () => {
+ const {container} = render(
+ <TextInput label="Name" value="" onChange={() => {}} isReadOnly />,
+ );
+ const root = container.querySelector('.astryx-text-input');
+ expect(root).toHaveAttribute('data-readonly', 'readonly');
+ });
+
+ it('omits data-readonly when editable', () => {
+ const {container} = render(
+ <TextInput label="Name" value="" onChange={() => {}} />,
+ );
+ const root = container.querySelector('.astryx-text-input');
+ expect(root).not.toHaveAttribute('data-readonly');
+ });
+});
diff --git a/packages/core/src/TextInput/TextInput.tsx b/packages/core/src/TextInput/TextInput.tsx
index 4767637ea5..36f3329786 100644
--- a/packages/core/src/TextInput/TextInput.tsx
+++ b/packages/core/src/TextInput/TextInput.tsx
@@ -166,6 +166,15 @@ export interface TextInputProps extends Omit<
* @default false
*/
isDisabled?: boolean;
+ /**
+ * Whether the input is read-only.
+ * The value is shown at full opacity and still submits with the form, but
+ * cannot be edited. Unlike `isDisabled`, a read-only input is not dimmed and
+ * stays in the tab order — use it for a value the user should see and send
+ * but not change. `isDisabled` takes precedence when both are set.
+ * @default false
+ */
+ isReadOnly?: boolean;
/**
* Explains why the input is disabled. When set together with `isDisabled`,
* the input shows a tooltip with this text on hover and keyboard focus, and
@@ -285,6 +294,7 @@ export function TextInput({
isOptional = false,
isRequired = false,
isDisabled = false,
+ isReadOnly = false,
disabledMessage,
startIcon,
status,
@@ -365,7 +375,7 @@ export function TextInput({
// Value can't change while showing a disabled message (the field is
// read-only and non-native-disabled), but guard the handler too so the
// optimistic value and callbacks never fire.
- if (isDisabled) {
+ if (isDisabled || isReadOnly) {
return;
}
const newValue = e.target.value;
@@ -408,6 +418,7 @@ export function TextInput({
size,
status: status?.type ?? null,
disabled: isDisabled ? 'disabled' : null,
+ readonly: isReadOnly ? 'readonly' : null,
}),
stylex.props(
inputWrapperStyles.base,
@@ -448,7 +459,7 @@ export function TextInput({
// keep the value from changing.
disabled={isDisabled && !showsDisabledMessage}
aria-disabled={showsDisabledMessage ? 'true' : undefined}
- readOnly={showsDisabledMessage || undefined}
+ readOnly={isReadOnly || showsDisabledMessage || undefined}
autoFocus={hasAutoFocus}
data-autofocus={hasAutoFocus || undefined}
aria-describedby={ariaDescribedBy}
@@ -458,7 +469,7 @@ export function TextInput({
aria-labelledby={ariaLabelledBy}
{...stylex.props(styles.input, isDisabled && styles.inputDisabled)}
/>
- {hasClear && value !== '' && !isDisabled && (
+ {hasClear && value !== '' && !isDisabled && !isReadOnly && (
<button
type="button"
onClick={handleClear}