Skip to content

[docs] Clarify that fieldRef.current.focusField() is the canonical way to focus a field #22937

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
michelengelen merged 4 commits into from
Jun 30, 2026
Merged

[docs] Clarify that fieldRef.current.focusField() is the canonical way to focus a field #22937

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e1bca34
clarifies that fieldRef.current.focusField() is the canonical way to …
michelengelen Jun 24, 2026
0d7883e
replaces inputRef.current.focus() with fieldRef.current.focusField() …
michelengelen Jun 25, 2026
b7b4e39
Apply suggestion from @LukasTy
michelengelen Jun 25, 2026
ae8b311
Merge branch 'master' into recipe/pickers/22592
michelengelen Jun 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/data/date-pickers/fields/ControlledSelectedSections.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ import { DateField } from '@mui/x-date-pickers/DateField';

export default function ControlledSelectedSections() {
const [selectedSections, setSelectedSections] = React.useState(null);
const inputRef = React.useRef(null);
const fieldRef = React.useRef(null);

const setSelectedSectionType = (selectedSectionType) => {
inputRef.current?.focus();
fieldRef.current?.focusField();
setSelectedSections(selectedSectionType);
};

Expand All @@ -30,7 +30,7 @@ export default function ControlledSelectedSections() {
</Button>
</Stack>
<DateField
inputRef={inputRef}
fieldRef={fieldRef}
selectedSections={selectedSections}
onSelectedSectionsChange={setSelectedSections}
/>
Expand Down
13 changes: 9 additions & 4 deletions docs/data/date-pickers/fields/ControlledSelectedSections.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,21 @@ import Stack from '@mui/material/Stack';
import Button from '@mui/material/Button';
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { FieldSectionType, FieldSelectedSections } from '@mui/x-date-pickers/models';
import {
FieldSectionType,
FieldSelectedSections,
FieldRef,
} from '@mui/x-date-pickers/models';
import { PickerValue } from '@mui/x-date-pickers/internals';
import { DateField } from '@mui/x-date-pickers/DateField';

export default function ControlledSelectedSections() {
const [selectedSections, setSelectedSections] =
React.useState<FieldSelectedSections>(null);
const inputRef = React.useRef<HTMLInputElement>(null);
const fieldRef = React.useRef<FieldRef<PickerValue>>(null);

const setSelectedSectionType = (selectedSectionType: FieldSectionType) => {
inputRef.current?.focus();
fieldRef.current?.focusField();
setSelectedSections(selectedSectionType);
};

Expand All @@ -31,7 +36,7 @@ export default function ControlledSelectedSections() {
</Button>
</Stack>
<DateField
inputRef={inputRef}
fieldRef={fieldRef}
selectedSections={selectedSections}
onSelectedSectionsChange={setSelectedSections}
/>
Expand Down
2 changes: 1 addition & 1 deletion docs/data/date-pickers/fields/ControlledSelectedSections.tsx.preview
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
</Button>
</Stack>
<DateField
inputRef={inputRef}
fieldRef={fieldRef}
selectedSections={selectedSections}
onSelectedSectionsChange={setSelectedSections}
/>
16 changes: 6 additions & 10 deletions docs/data/date-pickers/fields/ControlledSelectedSectionsMultiInputRangeField.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,14 @@ import { MultiInputDateRangeField } from '@mui/x-date-pickers-pro/MultiInputDate

export default function ControlledSelectedSectionsMultiInputRangeField() {
const [selectedSections, setSelectedSections] = React.useState(null);
const startInputRef = React.useRef(null);
const endInputRef = React.useRef(null);
const startFieldRef = React.useRef(null);
const endFieldRef = React.useRef(null);

const setSelectedSectionType = (selectedSectionType, position) => {
if (position === 'start') {
startInputRef.current?.focus();
startFieldRef.current?.focusField();
} else {
endInputRef.current?.focus();
endFieldRef.current?.focusField();
}
setSelectedSections(selectedSectionType);
};
Expand Down Expand Up @@ -47,12 +47,8 @@ export default function ControlledSelectedSectionsMultiInputRangeField() {
</Stack>
<MultiInputDateRangeField
sx={{ minWidth: 300 }}
slotProps={{
textField: (ownerState) => ({
inputRef:
ownerState.position === 'start' ? startInputRef : endInputRef,
}),
}}
startFieldRef={startFieldRef}
endFieldRef={endFieldRef}
selectedSections={selectedSections}
onSelectedSectionsChange={setSelectedSections}
/>
Expand Down
23 changes: 12 additions & 11 deletions docs/data/date-pickers/fields/ControlledSelectedSectionsMultiInputRangeField.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,29 @@ import Stack from '@mui/material/Stack';
import Button from '@mui/material/Button';
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { FieldSectionType, FieldSelectedSections } from '@mui/x-date-pickers/models';
import {
FieldSectionType,
FieldSelectedSections,
FieldRef,
} from '@mui/x-date-pickers/models';
import { PickerValue } from '@mui/x-date-pickers/internals';
import { RangePosition } from '@mui/x-date-pickers-pro/models';
import { MultiInputDateRangeField } from '@mui/x-date-pickers-pro/MultiInputDateRangeField';

export default function ControlledSelectedSectionsMultiInputRangeField() {
const [selectedSections, setSelectedSections] =
React.useState<FieldSelectedSections>(null);
const startInputRef = React.useRef<HTMLInputElement>(null);
const endInputRef = React.useRef<HTMLInputElement>(null);
const startFieldRef = React.useRef<FieldRef<PickerValue>>(null);
const endFieldRef = React.useRef<FieldRef<PickerValue>>(null);

const setSelectedSectionType = (
selectedSectionType: FieldSectionType,
position: RangePosition,
) => {
if (position === 'start') {
startInputRef.current?.focus();
startFieldRef.current?.focusField();
} else {
endInputRef.current?.focus();
endFieldRef.current?.focusField();
}
setSelectedSections(selectedSectionType);
};
Expand Down Expand Up @@ -52,12 +57,8 @@ export default function ControlledSelectedSectionsMultiInputRangeField() {
</Stack>
<MultiInputDateRangeField
sx={{ minWidth: 300 }}
slotProps={{
textField: (ownerState) => ({
inputRef:
ownerState.position === 'start' ? startInputRef : endInputRef,
}),
}}
startFieldRef={startFieldRef}
endFieldRef={endFieldRef}
selectedSections={selectedSections}
onSelectedSectionsChange={setSelectedSections}
/>
Expand Down
8 changes: 2 additions & 6 deletions docs/data/date-pickers/fields/ControlledSelectedSectionsMultiInputRangeField.tsx.preview
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,8 @@
</Stack>
<MultiInputDateRangeField
sx={{ minWidth: 300 }}
slotProps={{
textField: (ownerState) => ({
inputRef:
ownerState.position === 'start' ? startInputRef : endInputRef,
}),
}}
startFieldRef={startFieldRef}
endFieldRef={endFieldRef}
selectedSections={selectedSections}
onSelectedSectionsChange={setSelectedSections}
/>
4 changes: 1 addition & 3 deletions docs/data/date-pickers/fields/ControlledSelectedSectionsSingleInputRangeField.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,14 @@ import { SingleInputDateRangeField } from '@mui/x-date-pickers-pro/SingleInputDa

export default function ControlledSelectedSectionsSingleInputRangeField() {
const [selectedSections, setSelectedSections] = React.useState(null);
const inputRef = React.useRef(null);
const fieldRef = React.useRef(null);

const setSelectedSectionType = (selectedSectionType, position) => {
if (!fieldRef.current) {
return;
}

inputRef.current?.focus();
fieldRef.current.focusField();
const sections = fieldRef.current.getSections().map((el) => el.type);
setSelectedSections(
position === 'start'
Expand Down Expand Up @@ -55,7 +54,6 @@ export default function ControlledSelectedSectionsSingleInputRangeField() {
<SingleInputDateRangeField
sx={{ minWidth: 300 }}
fieldRef={fieldRef}
inputRef={inputRef}
selectedSections={selectedSections}
onSelectedSectionsChange={setSelectedSections}
/>
Expand Down
4 changes: 1 addition & 3 deletions docs/data/date-pickers/fields/ControlledSelectedSectionsSingleInputRangeField.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ import { SingleInputDateRangeField } from '@mui/x-date-pickers-pro/SingleInputDa
export default function ControlledSelectedSectionsSingleInputRangeField() {
const [selectedSections, setSelectedSections] =
React.useState<FieldSelectedSections>(null);
const inputRef = React.useRef<HTMLInputElement>(null);
const fieldRef = React.useRef<FieldRef<DateRange<Dayjs>>>(null);

const setSelectedSectionType = (
Expand All @@ -27,7 +26,7 @@ export default function ControlledSelectedSectionsSingleInputRangeField() {
return;
}

inputRef.current?.focus();
fieldRef.current.focusField();
const sections = fieldRef.current.getSections().map((el) => el.type);
setSelectedSections(
position === 'start'
Expand Down Expand Up @@ -64,7 +63,6 @@ export default function ControlledSelectedSectionsSingleInputRangeField() {
<SingleInputDateRangeField
sx={{ minWidth: 300 }}
fieldRef={fieldRef}
inputRef={inputRef}
selectedSections={selectedSections}
onSelectedSectionsChange={setSelectedSections}
/>
Expand Down
1 change: 0 additions & 1 deletion docs/data/date-pickers/fields/ControlledSelectedSectionsSingleInputRangeField.tsx.preview
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
<SingleInputDateRangeField
sx={{ minWidth: 300 }}
fieldRef={fieldRef}
inputRef={inputRef}
selectedSections={selectedSections}
onSelectedSectionsChange={setSelectedSections}
/>
5 changes: 5 additions & 0 deletions docs/data/date-pickers/fields/fields.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,4 +88,9 @@ You can also customize the icon you want to be displayed inside the clear `IconB

You can also interact with the field's value or sections programmatically using the `clearValue`, `focusField`, and other methods of the `fieldRef` (or `startFieldRef` and `endFieldRef` for multi-input fields).

:::success
Use `fieldRef.current.focusField()` to focus a field programmatically instead of `inputRef.current.focus()`.
The field renders a visually hidden `<input>` for form interop (so that `name`, native form submission, and `FormData` work as expected), and `focusField()` is the API that reliably focuses the visible section instead of that hidden element.
:::

{{"demo": "ImperativeClear.js"}}
Loading