# Charts Rules
Essential rules for PatternFly Charts implementation using Victory.js and ECharts.
## Installation Rules
### Required Installation
```bash
# ✅ Victory-based charts (recommended)
npm install @patternfly/react-charts victory
# ✅ ECharts-based charts (alternative)
npm install @patternfly/react-charts echarts
# ✅ Patternfly for charts css variables (recommended)
npm install @patternfly/patternfly
```
### Import Rules
- ✅ **CRITICAL: Use specific import paths** - Import from `/victory` or `/echarts` subdirectories
- ❌ **Don't use general imports** - Avoid importing from main package
- ⚠️ **Common Error**: AI assistants often forget the `/victory` path
```jsx
// ✅ Correct imports - MUST include /victory
import { ChartDonut, ChartLine, ChartBar } from '@patternfly/react-charts/victory';
import { EChart } from '@patternfly/react-charts/echarts';
// ❌ Wrong imports - Missing /victory will cause "Module not found" errors
import { ChartDonut } from '@patternfly/react-charts';
```
### Import PatternFly Charts CSS
```jsx
// In your main App.js or index.js
import '@patternfly/patternfly/patternfly-charts.css';
```
### Critical Import Path Troubleshooting
**⚠️ MOST COMMON ISSUE**: Chart components cannot be found
```bash
# Error message you'll see:
Module not found: Can't resolve '@patternfly/react-charts'
```
**Solutions in order:**
1. **Fix import paths** - Add `/victory` to your imports:
```jsx
// Change this:
import { ChartDonut } from '@patternfly/react-charts';
// To this:
import { ChartDonut } from '@patternfly/react-charts/victory';
```
2. **Install Victory dependency**:
```bash
npm install victory
```
3. **Clear cache and reinstall**:
```bash
rm -rf node_modules package-lock.json
npm install
```
4. **Verify installation**:
```bash
# Check if both packages are installed
npm list @patternfly/react-charts
npm list victory
```
## Chart Implementation Rules
### Best Practices
### Color families
- Chart color families include
- red-orange
- orange
- yellow
- teal
- green
- blue
- purple
- black
- Use the same brightness of colors first, then use other brightness
- Base: 300
- Lightest: 100
- Darkest: 500
- Second-lightest: 200
- Second-darkest: 400
- Use PatternFly tokens to define your color variables
- --pf-t-chart-color-[color-family]-[brightness]
- example: --pf-t-chart-color-blue-300
- When selecting colors for your chart, adhere to these general rules:
- Within a color family, use the base color first. Then use the other lighter and darker hues.
- Some families have predetermined uses:
- Blue: Use to show success.
- Red-orange: Use to show failure. Do not use this family unless you're communicating failure.
- Other colors: Use for neutral purposes or categories.
### Color Rules
- ✅ **Use PatternFly chart color tokens** - For consistency with design system
- ❌ **Don't use hardcoded colors** - Use design tokens instead
```jsx
// ✅ Correct - Use PatternFly color tokens
const chartBlueColor = [
'var(--pf-t--chart--color--[color family 1]--300)',
'var(--pf-t--chart--color--[color family 2]--300)',
'var(--pf-t--chart--color--[color family 3]--300)'
];
<ChartDonut data={data} colorScale={chartColors} />
```
### Responsive Rules
- ✅ **Implement responsive sizing** - Charts must work on all screen sizes
- ✅ **Use container-based dimensions** - Not fixed width/height
- ❌ **Don't hardcode dimensions** - Charts must be responsive
```jsx
// ✅ Required responsive pattern
const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
useEffect(() => {
const updateDimensions = () => {
if (containerRef.current) {
const { width, height } = containerRef.current.getBoundingClientRect();
setDimensions({ width, height });
}
};
updateDimensions();
window.addEventListener('resize', updateDimensions);
return () => window.removeEventListener('resize', updateDimensions);
}, []);
```
### Accessibility Rules
- ✅ **Provide ARIA labels** - For screen reader support
- ✅ **Use high contrast colors** - Meet WCAG standards
- ✅ **Support keyboard navigation** - Add tabIndex and role
```jsx
// ✅ Required accessibility pattern
<ChartDonut
data={data}
ariaDesc="Chart showing user distribution"
ariaTitle="User Status Chart"
tabIndex={0}
role="img"
/>
```
### State Management Rules
- ✅ **Handle loading states** - Show spinners during data loading
- ✅ **Handle error states** - Show error messages with retry
- ✅ **Handle empty states** - Show appropriate empty messages
- ✅ **Use data memoization** - For performance optimization
```jsx
// ✅ Required state handling
if (isLoading) return <Spinner />;
if (error) return <EmptyState><EmptyStateHeader titleText="Chart error" /></EmptyState>;
if (!data?.length) return <EmptyState><EmptyStateHeader titleText="No data" /></EmptyState>;
const processedData = useMemo(() => {
return rawData.map(item => ({ x: item.date, y: item.value }));
}, [rawData]);
```
### Integration Rules
- ✅ **Use with PatternFly components** - Integrate charts in Cards, PageSections
- ✅ **Follow grid layouts** - Use PatternFly grid for chart dashboards
- ❌ **Don't create standalone chart pages** - Integrate with PatternFly layout
```jsx
// ✅ Required integration pattern
import { Card, CardTitle, CardBody } from '@patternfly/react-core';
<Card>
<CardTitle>Chart Title</CardTitle>
<CardBody>
<ChartDonut data={data} />
</CardBody>
</Card>
```
## Performance Rules
### Required Optimizations
- ✅ **Use lazy loading for heavy charts** - Improve initial page load
- ✅ **Memoize data processing** - Use useMemo for expensive calculations
- ✅ **Implement proper loading states** - Show feedback during data loading
```jsx
// ✅ Required performance patterns
const LazyChart = lazy(() => import('./HeavyChart'));
<Suspense fallback={<Spinner />}>
<LazyChart />
</Suspense>
```
## Essential Do's and Don'ts
### ✅ Do's
- Use PatternFly chart color tokens for consistency
- Implement responsive sizing for different screen sizes
- Provide proper ARIA labels and descriptions
- Handle loading, error, and empty states
- Use appropriate chart types for your data
- Optimize performance with data memoization
- Integrate charts with PatternFly layout components
### ❌ Don'ts
- Hardcode chart dimensions without responsive design
- Use colors that don't meet accessibility standards
- Skip loading states for charts with async data
- Ignore keyboard navigation and screen reader support
- Create overly complex charts
- Mix different charting libraries inconsistently
- Forget to handle empty data states
## Common Issues
### Module Not Found
- **Clear cache**: `rm -rf node_modules package-lock.json`
- **Reinstall**: `npm install`
- **Check paths**: Verify import paths are correct
### Chart Not Rendering
- **Check container dimensions**: Ensure parent has width/height
- **Verify data format**: Data must match chart expectations
- **Check console**: Look for Victory.js or ECharts warnings
### Performance Issues
- **Use data memoization**: useMemo for expensive calculations
- **Implement lazy loading**: For heavy chart components
- **Optimize re-renders**: Use React.memo for chart components
#### Issue: Chart colors not correct
```bash
# Symptoms: Chart color variables (--pf-v6-chart-color-blue-100, --pf-t--chart--color--blue--300) are not defined
```
**Solutions**:
1. **Install patternfly package**:
```bash
npm install @patternfly/patternfly
```
2. **Import PatternFly Charts CSS**:
```jsx
// In your main App.js or index.js
import '@patternfly/patternfly/patternfly-charts.css';
```
## Quick Reference
- **[PatternFly Charts README](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts#readme)** - Installation and usage
- **[Victory.js Documentation](https://formidable.com/open-source/victory/)** - Chart library documentation
- **[PatternFly Chart Guidelines](https://www.patternfly.org/charts/about-charts)** - Design guidelines
- **[PatternFly Chart Colors](https://www.patternfly.org/charts/colors-for-charts)** - Colors for charts
## Reference Documentation
- [PatternFly Charts on PatternFly.org](https://www.patternfly.org/charts/about)
- [PatternFly React Charts GitHub Repository](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts)
> For the most up-to-date documentation and code examples, consult both PatternFly.org and the official GitHub repository. When using AI tools, leverage context7 to fetch the latest docs from these sources.
