{"record":{"id":"cd8d544a2fc69779","repo":"marmelab/react-admin","slug":"usepreference-cannot-be-used-outside-of-a-configur","errorCode":null,"errorMessage":"usePreference cannot be used outside of a Configurable component. Did you forget to wrap your component with <Configurable>? If you don't want to use Configurable, you can use the useStore hook instead.","messagePattern":"usePreference cannot be used outside of a Configurable component\\. Did you forget to wrap your component with <Configurable>\\? If you don't want to use Configurable, you can use the useStore hook instead\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/ra-core/src/preferences/usePreference.ts","lineNumber":33,"sourceCode":"function usePreference<T>(\n    key: string,\n    defaultValue: T\n): [T, (value: T | ((value: T) => void), defaultValue?: T) => void];\nfunction usePreference<T = undefined>(\n    key: string,\n    defaultValue?: T | undefined\n): [T | undefined, (value: T | ((value: T) => void), defaultValue?: T) => void];\nfunction usePreference(): [\n    unknown,\n    (\n        value: unknown | ((value: unknown) => void),\n        defaultValue?: unknown\n    ) => void,\n];\nfunction usePreference<T>(key = '', defaultValue = undefined) {\n    const preferenceKey = usePreferenceKey();\n    if (!preferenceKey) {\n        throw new Error(\n            \"usePreference cannot be used outside of a Configurable component. Did you forget to wrap your component with <Configurable>? If you don't want to use Configurable, you can use the useStore hook instead.\"\n        );\n    }\n\n    return useStore<T>(\n        preferenceKey && key ? `${preferenceKey}.${key}` : preferenceKey ?? key,\n        defaultValue\n    );\n}\n\nexport { usePreference };\n","sourceCodeStart":15,"sourceCodeEnd":45,"githubUrl":"https://github.com/marmelab/react-admin/blob/051f511bb0afb5ea565c2d3728bf4dab0a6fa5e0/packages/ra-core/src/preferences/usePreference.ts#L15-L45","documentation":"usePreference reads a value from the preferences scoped by the current <Configurable> component; it derives a preference key from usePreferenceKey(). Inside a Configurable subtree the key exists; outside it is empty, and react-admin throws rather than silently reading from an unintended global store. The error message suggests useStore for key/value state without Configurable.","triggerScenarios":"Calling usePreference(key, defaultValue) in a component not rendered inside <Configurable>; using it in the editor UI code outside the PreferencesEditor scope; calling it conditionally where the preferenceKey becomes empty at runtime.","commonSituations":"Reusing a Configurable child component elsewhere in the app (outside Configurable) after extracting it; writing custom inputs for the preferences editor and forgetting the wrapper; migration from useStore to usePreference without adding Configurable.","solutions":["Wrap the component with <Configurable> (giving it an editor component) so a preference key is injected.","Replace usePreference with useStore(key, defaultValue) if you don't need the Configurable scoping, as the message suggests.","Pass the preference key explicitly through your own context/props if you must read preferences outside the subtree."],"exampleFix":"// before\nconst PrefValue = () => {\n    const [value] = usePreference('myKey', 'default'); // throws outside Configurable\n    return <span>{value}</span>;\n};\n\n// after\nimport { Configurable } from 'react-admin';\n<Configurable editor={<MyEditor />} preferenceKey=\"my-component\">\n    <PrefValue />\n</Configurable>;\n// or, without Configurable:\nconst PrefValue = () => {\n    const [value] = useStore('myKey', 'default');\n    return <span>{value}</span>;\n};","handlingStrategy":"validation","validationCode":"import { useContext } from 'react';\nimport { PreferenceKeyContext } from 'ra-core';\nconst preferenceKey = useContext(PreferenceKeyContext);\nif (!preferenceKey) {\n    const [value] = useStore('myKey', 'default'); // fallback path\n}","typeGuard":"const hasPreferenceKey = (v: string | undefined | null): v is string => typeof v === 'string' && v.length > 0;","tryCatchPattern":null,"preventionTips":["Pair every usePreference call with a <Configurable> wrapper in the same component.","Use useStore when state must work with and without Configurable.","Never reuse a Configurable child component outside its Configurable subtree."],"tags":["react","context","preferences","hooks"],"backgroundTag":"react-hook-outside-provider","analyzedSha":"051f511bb0afb5ea565c2d3728bf4dab0a6fa5e0","analyzedAt":"2026-08-30T02:28:14.926Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}