Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Autocomplete
✓ import { Autocomplete } from 'formik-mui-lab';
✗ const Autocomplete = require('formik-mui-lab').Autocomplete;
Use named import for ES Modules. CommonJS `require` is not officially supported for modern Formik-MUI versions.
Rating
✓ import { Rating } from 'formik-mui-lab';
✗ import Rating from 'formik-mui-lab/Rating';
Components are directly exported from the main package entry point, not nested paths.
ToggleButtonGroup
✓ import { ToggleButtonGroup } from 'formik-mui-lab';
✗ import { ToggleButtonGroupField } from 'formik-mui-lab';
The component names usually mirror the original MUI Lab component names directly.
This example demonstrates how to use Formik-MUI Lab's Autocomplete and Rating components within a Formik form, showing form submission and state management.
import React from 'react';
import { Formik, Form, Field } from 'formik';
import { Autocomplete, Rating } from 'formik-mui-lab';
import { TextField, Button, Box, Typography } from '@mui/material';
interface MyFormValues {
favoriteColor: string | null;
userRating: number | null;
}
const initialValues: MyFormValues = {
favoriteColor: null,
userRating: null,
};
const colorOptions = ['Red', 'Green', 'Blue', 'Yellow', 'Purple'];
function MyForm() {
return (
<Box sx={{ p: 3, maxWidth: 500, mx: 'auto', border: '1px solid #ccc', borderRadius: '8px' }}>
<Typography variant="h5" component="h1" gutterBottom>
Formik MUI Lab Example
</Typography>
<Formik
initialValues={initialValues}
onSubmit={(values, { setSubmitting }) => {
setTimeout(() => {
alert(JSON.stringify(values, null, 2));
setSubmitting(false);
}, 500);
}}
>
{({ submitForm, isSubmitting, values }) => (
<Form>
<Field
component={Autocomplete}
name="favoriteColor"
label="Favorite Color"
options={colorOptions}
getOptionLabel={(option: string) => option}
sx={{ mb: 2 }}
renderInput={(params: any) => <TextField {...params} label="Favorite Color" variant="outlined" />} // `any` for simplicity
isOptionEqualToValue={(option: string, value: string) => option === value}
/>
<Box sx={{ display: 'flex', alignItems: 'center', mb: 2 }}>
<Typography component="legend" sx={{ mr: 1 }}>Your Rating:</Typography>
<Field
component={Rating}
name="userRating"
max={5}
precision={0.5}
/>
</Box>
<Button
type="submit"
variant="contained"
color="primary"
disabled={isSubmitting}
>
Submit
</Button>
<pre style={{ marginTop: '16px', backgroundColor: '#f0f0f0', padding: '10px', borderRadius: '4px' }}>
{JSON.stringify(values, null, 2)}
</pre>
</Form>
)}
</Formik>
</Box>
);
}
export default MyForm;
Debug
Known issues
breakingVersion 1.0.0 (and its alpha pre-releases) fully upgrades to Material-UI v5. This introduces significant breaking changes for applications still using Material-UI v4, particularly concerning styling solutions (Emotion replacing JSS) and API changes.fixUpgrade your project's Material-UI packages (`@mui/material`, `@mui/lab`, etc.) to v5. Refer to the official Material-UI v5 migration guide for details on API and styling changes. Ensure `@emotion/react` and `@emotion/styled` are installed.
affects: >=1.0.0-alpha.1
breakingThis package requires Formik version 2.0.0 or higher. Using an older version of Formik will result in compatibility issues or runtime errors, as the internal APIs used by the bindings have changed significantly.fixUpgrade your Formik package to version 2.0.0 or later: `npm install formik@^2.0.0` or `yarn add formik@^2.0.0`.
affects: <2.0.0 of formik
gotchaThe `renderInput` prop for Autocomplete components, which is crucial for displaying the text input, often requires an MUI `TextField`. Ensure you import and provide this component correctly, along with spreading `params` to it.fixAlways provide a `renderInput` prop to `Autocomplete` components, usually a `<TextField {...params} />` from `@mui/material`. Remember to import `TextField` separately: `import { TextField } from '@mui/material';`. affects: >=1.0.0
gotchaWhile the `pickers` keyword is present, this package primarily wraps components from `@mui/lab`. Date and Time Picker components are now part of `@mui/x-date-pickers` and are not directly provided as wrappers by `formik-mui-lab`.fixFor Formik bindings with Date/Time Pickers, you should look for `formik-mui-x-date-pickers` or similar community packages that specifically target `@mui/x-date-pickers`. Do not expect these components to be exported from `formik-mui-lab`.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'field')
This typically occurs when a Formik-MUI Lab component is used outside of a Formik context, or if the `name` prop is missing from the `Field` component.
fixEnsure your component is rendered within a `<Formik>` and `<Form>` component. Verify that the `Field` component has a `name` prop matching a key in your `initialValues`.
Invariant Violation: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined.
This error often indicates that a component imported from `formik-mui-lab` is undefined, usually due to a misspelling in the import or the component not being exported from the package.
fixDouble-check the component name in your import statement (e.g., `Autocomplete`, `Rating`) and ensure it is correctly destructured from `formik-mui-lab`.
TypeError: Invalid hook call. Hooks can only be called inside of the body of a function component.
This package, like Formik and Material-UI, relies on React Hooks. This error can occur if you have multiple versions of React installed, or incorrect build configurations.
fixEnsure you have a single, consistent version of React installed across your project. Check your `package-lock.json` or `yarn.lock` for duplicate React entries. Clear node_modules and reinstall dependencies.
Audit
Dependencies
@emotion/reactrequiredRequired by Material-UI (MUI 5+) for styling.
@emotion/styledrequiredRequired by Material-UI (MUI 5+) for styling.
@mui/labrequiredThe core Material-UI Lab components that this package provides Formik bindings for.
@mui/materialrequiredThe core Material-UI components framework that `@mui/lab` builds upon.
formikrequiredThe form state management library that this package integrates with.
reactrequiredThe base UI library for all React components.
tiny-warningoptionalA small utility for displaying development warnings.