{"record":{"id":"4021d6a5a3debca2","repo":"necolas/react-native-web","slug":"the-image-component-cannot-contain-children-if","errorCode":null,"errorMessage":"The <Image> component cannot contain children. If you want to render content on top of the image, consider using the <ImageBackground> component or absolute positioning.","messagePattern":"The <Image> component cannot contain children\\. If you want to render content on top of the image, consider using the <ImageBackground> component or absolute positioning\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/react-native-web/src/exports/Image/index.js","lineNumber":199,"sourceCode":"    accessibilityLabel,\n    blurRadius,\n    defaultSource,\n    draggable,\n    onError,\n    onLayout,\n    onLoad,\n    onLoadEnd,\n    onLoadStart,\n    pointerEvents,\n    source,\n    style,\n    ...rest\n  } = props;\n  const ariaLabel = _ariaLabel || accessibilityLabel;\n\n  if (process.env.NODE_ENV !== 'production') {\n    if (props.children) {\n      throw new Error(\n        'The <Image> component cannot contain children. If you want to render content on top of the image, consider using the <ImageBackground> component or absolute positioning.'\n      );\n    }\n  }\n\n  const [state, updateState] = React.useState(() => {\n    const uri = resolveAssetUri(source);\n    if (uri != null) {\n      const isLoaded = ImageLoader.has(uri);\n      if (isLoaded) {\n        return LOADED;\n      }\n    }\n    return IDLE;\n  });\n\n  const [layout, updateLayout] = React.useState({});\n  const hasTextAncestor = React.useContext(TextAncestorContext);","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/necolas/react-native-web/blob/a9de220ba9e65bdea540fb5322ffb1da2b0bf442/packages/react-native-web/src/exports/Image/index.js#L181-L217","documentation":"HTML/CSS cannot reliably render nested content inside an <img>-backed element the way native UIImageView+subviews can, so react-native-web forbids children on <Image>. The library provides <ImageBackground> (which renders a wrapper with the image as a child layer) for overlaying content. The check only runs in development (NODE_ENV !== 'production').","triggerScenarios":"Rendering any children inside <Image> in a non-production build, e.g. <Image source={...}><Text>label</Text></Image>.","commonSituations":"Migrating code from React Native where placing children in Image was tolerated or common before RN deprecated it; adding badges/overlays on top of avatars; following old RN tutorials.","solutions":["Replace <Image> with <ImageBackground> when children are needed.","Or position the overlay outside the Image with absolute positioning inside a wrapper View.","If no children are intended, remove the stray JSX inside <Image>."],"exampleFix":"// before\n<Image source={img}><Text>Hi</Text></Image>\n// after\n<ImageBackground source={img}>\n  <Text>Hi</Text>\n</ImageBackground>","handlingStrategy":"validation","validationCode":"function assertNoImageChildren(props) {\n  if (process.env.NODE_ENV !== 'production' && props.children != null) {\n    throw new Error('Use <ImageBackground> instead of <Image> with children.');\n  }\n}","typeGuard":"const needsImageBackground = (children) => children != null;","tryCatchPattern":"try { return <Image {...props} />; } catch (e) { if (/cannot contain children/.test(e.message)) return <ImageBackground {...props} />; throw e; }","preventionTips":["Default to <ImageBackground> whenever overlay content is needed","Add a lint rule/ESLint plugin to flag children inside <Image>","Review RN->web ports for legacy <Image> nesting"],"tags":["react-native-web","image","children-not-allowed","dev-only"],"backgroundTag":"component-does-not-accept-children","analyzedSha":"a9de220ba9e65bdea540fb5322ffb1da2b0bf442","analyzedAt":"2026-09-01T10:01:09.883Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}