# Crownpeak DQM React Component
[](https://www.npmjs.com/package/@crownpeak/dqm-react-component)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://reactjs.org/)
A React component library for integrating [Crownpeak Digital Quality Management (DQM)](https://www.crownpeak.com/) into
your React applications. Display quality analysis, accessibility violations, and checkpoint errors with visual
highlighting capabilities.
## ๐ Features
- **๐ค AI-Powered Translation & Summary** - Automatically translate analysis results into your language and generate intelligent summaries using OpenAI
- **๐ Quality Analysis** - Comprehensive quality metrics and scores
- **โฟ Accessibility Checks** - WCAG compliance validation
- **๐ฏ Error Highlighting** - Visual highlighting of issues in HTML
- **๐จ Material-UI Design** - Beautiful, responsive sidebar interface
- **๐ Secure Authentication** - Backend session management with secure credential storage
- **โก Real-time Analysis** - Live quality assessment as you edit
- **๐ฑ Responsive** - Works on desktop, tablet, and mobile
- **๐ Internationalization** - Supports English, German, and Spanish
- **๐ง TypeScript Support** - Full type definitions included
## ๐ฆ Installation
```bash
npm install @crownpeak/dqm-react-component
```
## ๐ Quick Start
```tsx
import React, {useState} from 'react';
import {DQMSidebar} from '@crownpeak/dqm-react-component';
function App() {
const [open, setOpen] = useState(false);
const customHtml = `
Test Page
Hello World
`
return (
setOpen(true)}
onClose={() => setOpen(false)}
debugHtml={customHtml}
config={{
// ... authentication options here
// look for "๐ Authentication Setup" below
}}
/>
);
}
export default App;
```
### AI-Powered Translation & Summary (Quick Example)
```typescript
import {DQMSidebar} from '@crownpeak/dqm-react-component';
setIsOpen(false)}
onOpen={() => setIsOpen(true)}
config={{
websiteId: 'your-website-id',
apiKey: 'your-api-key',
// Enable AI Translation (API key via localStorage: dqm_openai_apiKey)
translation: {
enabledByDefault: true,
computeBudgetMs: 15000, // 15s timeout for 'fast' mode
},
// Enable AI Summary (uses same OpenAI API key)
summary: {
timeoutMs: 30000, // 30s timeout
}
}}
/>
```
See **[AI Features Guide](./docs/AI-FEATURES.md)** for complete documentation including caching strategies and performance tuning.
## ๐ Documentation
### Core Documentation
- **[Quick Start Guide](./docs/QUICKSTART.md)** - Get up and running in 5 minutes
- **[Examples](./docs/EXAMPLES.md)** - Integration examples for React, Next.js, TypeScript
- **[Authentication Guide](./docs/AUTHENTICATION.md)** - Setup and configuration
### AI Features
- **[AI Features Guide](./docs/AI-FEATURES.md)** - Translation & Summary with OpenAI
- **[API Reference](./docs/API-REFERENCE.md)** - Full TypeScript API documentation
- **[Migration Guide](./docs/MIGRATION-GUIDE.md)** - Upgrade from v1.1 to v1.2
### Advanced
- **[Widget Guide](./docs/WIDGET-GUIDE.md)** - Standalone IIFE/ESM bundle usage
- **[Backend API](./docs/BACKEND-API.md)** - Backend server endpoints and usage
- **[Development Guide](./docs/DEVELOPMENT.md)** - Contributing and local development
- **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues and solutions
## ๐ Authentication Setup
The component requires authentication with Crownpeak DQM. Two options are available:
```tsx
import {DQMSidebar} from '@crownpeak/dqm-react-component';
void` | โ
| Callback when sidebar closes |
| `onOpen` | `() => void` | โ
| Callback when sidebar opens |
| `debugHtml` | `string` | โ | HTML for testing (dev only) |
| `config` | `DQMConfig` | โ | Configuration options |
### DQMConfig Options
| Option | Type | Default | Description |
|-------------------|-----------------|---------|------------------------------------------------|
| `apiKey` | `string` | - | Direct API key (not for production) |
| `websiteId` | `string` | - | Website ID for DQM |
| `authBackendUrl` | `string` | - | Backend URL for session management |
| `useLocalStorage` | `boolean` | `true` | Persist credentials in localStorage |
| `disabled` | `boolean` | `false` | Disable DQM completely |
| `disableLogout` | `boolean` | `false` | Hide the logout control (host manages session) |
| `shadowDomMode` | `boolean` | `false` | Enable for Shadow DOM embedding |
| `overlayConfig` | `OverlayConfig` | - | Overlay/toolbar detection config |
### OverlayConfig (for Toolbars & Overlays)
Configure how the sidebar adapts to fixed overlays (e.g., admin toolbars):
```tsx
```
**Common overlay configurations:**
[//]: # (@formatter:off)
```tsx
// Disable overlay detection
overlayConfig: {
selector: null
}
// Manual 50px offset from top
overlayConfig: {
manualOffset: {
position: 'top', pixels: 50
}
}
// Custom selector without iFrame validation
overlayConfig: {
selector: '.admin-toolbar', validateIframe: false
}
```
[//]: # (@formatter:on)
### Exported Types
```typescript
import type {
AnalysisState,
Checkpoint,
AnalysisData,
DQMSidebarProps,
DQMConfig,
OverlayConfig,
OverlayOffsetPosition
} from '@crownpeak/dqm-react-component';
// For advanced overlay handling
import {useOverlayResistant} from '@crownpeak/dqm-react-component';
import type {OverlayInfo, OverlayPosition} from '@crownpeak/dqm-react-component';
```
See [TypeScript examples](./EXAMPLES.md#typescript-configuration) for full type definitions.
## ๐งช Testing
```bash
# Lint code
npm run lint
# Build library
npm run build:lib
# Test as package
npm pack
npm install ./crownpeak-dqm-react-component-1.0.0.tgz
```
## ๐ค Contributing
We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## ๐ License
MIT ยฉ [Crownpeak Technology GmbH](https://www.crownpeak.com/)
See [LICENSE](./LICENSE) file for details.
## ๐ Issues
Found a bug or have a feature request?
Please [open an issue](https://github.com/Crownpeak/dqm-react-component/issues/new/choose).
## ๐ Support
- **Documentation**: Check the [docs folder](.)
- **Issues**: [GitHub Issues](https://github.com/Crownpeak/dqm-react-component/issues)
- **Website**: [crownpeak.com](https://www.crownpeak.com/)
## ๐ Links
- [NPM Package](https://www.npmjs.com/package/@crownpeak/dqm-react-component)
- [GitHub Repository](https://github.com/Crownpeak/dqm-react-component)
- [Material-UI Documentation](https://mui.com/)
## ๐ Changelog
See [CHANGELOG.md](./CHANGELOG.md) for release history.
---
Made with โค๏ธ by the Crownpeak team