{"record":{"id":"47da4bc9b2463544","repo":"tailwindlabs/headlessui","slug":"invalid-role-role-passed-to-dialog-only-47da4b","errorCode":null,"errorMessage":"Invalid role [${role}] passed to <Dialog />. Only `dialog` and and `alertdialog` are supported. Using `dialog` instead.","messagePattern":"Invalid role \\[(.+?)\\] passed to <Dialog />\\. Only `dialog` and and `alertdialog` are supported\\. Using `dialog` instead\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/@headlessui-react/src/components/dialog/dialog.tsx","lineNumber":146,"sourceCode":"    onClose,\n    initialFocus,\n    role = 'dialog',\n    autoFocus = true,\n    __demoMode = false,\n    unmount = false,\n    ...theirProps\n  } = props\n\n  let didWarnOnRole = useRef(false)\n\n  role = (function () {\n    if (role === 'dialog' || role === 'alertdialog') {\n      return role\n    }\n\n    if (!didWarnOnRole.current) {\n      didWarnOnRole.current = true\n      console.warn(\n        `Invalid role [${role}] passed to <Dialog />. Only \\`dialog\\` and and \\`alertdialog\\` are supported. Using \\`dialog\\` instead.`\n      )\n    }\n\n    return 'dialog'\n  })()\n\n  let usesOpenClosedState = useOpenClosed()\n  if (open === undefined && usesOpenClosedState !== null) {\n    // Update the `open` prop based on the open closed state\n    open = (usesOpenClosedState & State.Open) === State.Open\n  }\n\n  let internalDialogRef = useRef<HTMLElement | null>(null)\n  let dialogRef = useSyncRefs(internalDialogRef, ref)\n\n  let ownerDocument = useOwnerDocument(internalDialogRef.current)\n","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/tailwindlabs/headlessui/blob/eea57cf46fd6767ed1059012f7073b88eb159fba/packages/@headlessui-react/src/components/dialog/dialog.tsx#L128-L164","documentation":"This console.warn comes from the Headless UI React <Dialog /> component when the `role` prop is set to anything other than 'dialog' or 'alertdialog'. The component falls back to role=\"dialog\" but warns once (a ref-based didWarnOnRole flag limits it to a single warning). It guards against invalid WAI-ARIA dialog roles, since only those two roles are valid for modals.","triggerScenarios":"Passing a non-standard or misspelled role to <Dialog role=\"...\">, e.g. role=\"modal\", role=\"alert-dialog\", role=\"Dialog\" (case-sensitive), or a ternary that evaluates to undefined/null instead of a valid string.","commonSituations":"Spreading props from another component into <Dialog> that includes a conflicting `role`; computing role conditionally (role={isAlert ? 'alertdialog' : undefined} where undefined wasn't intended); upgrading from an older version that accepted arbitrary roles; copy-paste from non-modal overlay code.","solutions":["Set role to a valid value: <Dialog role=\"alertdialog\"> for confirmation/destructive modals, or omit the prop entirely (defaults to 'dialog').","Type the variable as `'dialog' | 'alertdialog' | undefined` so TypeScript catches bad values before runtime.","Audit prop spreads (<Dialog {...props}>) for a stray `role` coming from parent components."],"exampleFix":"// before\n<Dialog role=\"modal\" onClose={close}>\n{/* warns: Invalid role [modal] */}\n\n// after\n<Dialog role=\"dialog\" onClose={close}>\n\n{/* or for confirmation dialogs */}\n<Dialog role=\"alertdialog\" onClose={close}>","handlingStrategy":"type-guard","validationCode":"const VALID_ROLES = ['dialog', 'alertdialog'] as const\n// before render\nconst role = isValidDialogRole(props.modalRole) ? props.modalRole : 'alertdialog'\nreturn <Dialog role={role} onClose={onClose}>...</Dialog>","typeGuard":"type DialogRole = 'dialog' | 'alertdialog'\nfunction isValidDialogRole(role: unknown): role is DialogRole {\n  return role === 'dialog' || role === 'alertdialog'\n}","tryCatchPattern":null,"preventionTips":["Type role props as `'dialog' | 'alertdialog'` (or omit the prop) so TypeScript rejects bad values.","Avoid blindly spreading props (<Dialog {...rest}>) that may carry a foreign `role`.","Use 'alertdialog' only for confirmation/destructive modals per ARIA authoring practices."],"tags":["headlessui","react","dialog","aria-role","accessibility","props-validation"],"backgroundTag":"invalid-aria-role","analyzedSha":"eea57cf46fd6767ed1059012f7073b88eb159fba","analyzedAt":"2026-08-28T19:22:46.163Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}