{"id":17380,"library":"swagger-ui-react","title":"Swagger UI for React","description":"swagger-ui-react is a specialized React component that seamlessly integrates Swagger UI directly into React applications. It exposes the full capabilities of Swagger UI through a simple React component, `SwaggerUI`. Unlike the core Swagger UI distribution, this package declares `react` and `react-dom` (versions >=16.8.0 <20) as peer dependencies, ensuring compatibility with existing React environments. The package's versioning closely mirrors the underlying Swagger UI, with the current stable release being 5.32.4. It receives frequent updates, including bug fixes, performance enhancements, and crucial security patches, as demonstrated by recent releases addressing several CVEs and introducing features like basic OpenAPI 3.2.0 support and dark mode. A notable aspect is the inclusion of anonymized installation analytics via Scarf, which users can easily opt out of through `package.json` settings or an environment variable. Developers should be mindful of specific prop behaviors, such as `layout` and `docExpansion` applying only on initial mount, and the mutual exclusivity of the `spec` and `url` props.","status":"active","version":"5.32.4","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/swagger-api/swagger-ui","tags":["javascript"],"install":[{"cmd":"npm install swagger-ui-react","lang":"bash","label":"npm"},{"cmd":"yarn add swagger-ui-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add swagger-ui-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the React component to function.","package":"react","optional":false},{"reason":"Required peer dependency for rendering the React component.","package":"react-dom","optional":false}],"imports":[{"note":"Primary component for rendering Swagger UI. This is an ESM default export.","wrong":"const SwaggerUI = require(\"swagger-ui-react\");","symbol":"SwaggerUI","correct":"import SwaggerUI from \"swagger-ui-react\";"},{"note":"Required to style the Swagger UI component. The correct path is directly under the package root.","wrong":"import \"swagger-ui-react/dist/swagger-ui.css\";","symbol":"CSS","correct":"import \"swagger-ui-react/swagger-ui.css\";"},{"note":"Use `import type` for type-only imports in TypeScript environments.","symbol":"Props (TypeScript)","correct":"import type { SwaggerUIProps } from \"swagger-ui-react\";"}],"quickstart":{"code":"import React from \"react\";\nimport SwaggerUI from \"swagger-ui-react\";\nimport \"swagger-ui-react/swagger-ui.css\";\n\nconst App = () => {\n  const apiUrl = process.env.REACT_APP_SWAGGER_URL || \"https://petstore.swagger.io/v2/swagger.json\";\n  const initialDocExpansion = \"list\"; // 'list', 'full', 'none'\n\n  return (\n    <div style={{ padding: '20px' }}>\n      <h1>My API Documentation</h1>\n      <SwaggerUI \n        url={apiUrl} \n        docExpansion={initialDocExpansion}\n        requestInterceptor={(req) => {\n          // Example: Add an authorization header\n          // req.headers.Authorization = `Bearer ${someAuthToken}`;\n          return req;\n        }}\n        onComplete={(system) => {\n          console.log(\"Swagger UI finished rendering.\", system);\n        }}\n      />\n    </div>\n  );\n};\n\nexport default App;\n","lang":"typescript","description":"This quickstart demonstrates how to integrate `SwaggerUI` into a React component, loading an OpenAPI specification from a URL, applying initial documentation expansion settings, and including basic interceptor and completion callbacks. It also shows a common pattern for defining the API URL via environment variables."},"warnings":[{"fix":"Consult the official Swagger UI release notes for breaking changes before upgrading. Test thoroughly in a staging environment.","message":"Major versions of `swagger-ui-react` correspond to `swagger-ui` releases. Upgrading major versions may introduce breaking changes in API behavior, configuration options, or UI rendering. Always review the `swagger-ui` changelog when updating major versions.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always use either `spec` (for inline JSON/YAML) OR `url` (for remote fetching), but never both simultaneously.","message":"The `spec` and `url` props are mutually exclusive. Providing both can lead to unpredictable behavior in how the OpenAPI document is loaded and displayed.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If dynamic changes to these specific props are required, consider remounting the `SwaggerUI` component (e.g., by changing its `key` prop) or explore using the Swagger UI system object obtained via `onComplete` for programmatic control.","message":"Certain props, such as `layout` and `docExpansion`, are currently only applied once on initial mount of the component. Subsequent changes to these props will not cause the underlying Swagger UI instance to update.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To opt out, set `\"scarfSettings\": { \"enabled\": false }` in your `package.json` or set the environment variable `SCARF_ANALYTICS=false` during installation.","message":"This package uses Scarf for anonymized installation analytics. This only occurs during `npm install` and helps support maintainers.","severity":"gotcha","affected_versions":">=5.x"},{"fix":"Ensure you are on the latest patch release to benefit from security updates. Review the changelog for specific dependency bumps.","message":"Recent versions (e.g., v5.32.4, v5.32.2) include fixes for high-severity CVEs in underlying Docker images and dependencies like `libpng` and `zlib`. While these are primarily for Docker users, dependency updates in patch releases can sometimes introduce subtle behavioral changes.","severity":"breaking","affected_versions":">=5.30.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Add `import \"swagger-ui-react/swagger-ui.css\";` to your component or main application file to ensure styles are loaded.","cause":"The CSS file for Swagger UI styling is not imported or the import path is incorrect.","error":"Module not found: Error: Can't resolve 'swagger-ui-react/swagger-ui.css'"},{"fix":"Ensure you are using `import SwaggerUI from \"swagger-ui-react\";` for the default export.","cause":"The `SwaggerUI` component was likely imported incorrectly, often as a CommonJS `require()` or as a named import when it's a default export.","error":"Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object."},{"fix":"Install `react` and `react-dom` in your project with versions compatible with `swagger-ui-react` (e.g., `npm install react react-dom`). The current peer dependency range is `>=16.8.0 <20`.","cause":"`react` or `react-dom` peer dependencies are not met or are not installed in your project.","error":"npm ERR! ERESOLVE unable to resolve dependency tree ... peer react@\"...\" from swagger-ui-react@..."},{"fix":"Ensure that props passed to `SwaggerUI` are stable during a render. If `url` or `spec` need to change, ensure the change is triggered by a user interaction or a state update outside of the direct render function flow, or consider using `React.memo` or `useMemo` for complex prop values.","cause":"Attempting to update a Swagger UI prop (e.g., `url` or `spec`) based on state changes within the same render cycle can lead to React warnings.","error":"Warning: Cannot update a component (`SwaggerUI`) while rendering a different component (`App`)."}],"ecosystem":"npm","meta_description":null}