Generic help panel component for Amplify UI #6667
Description
Is this related to a new or existing framework?
React
Is this related to a new or existing API?
New API
Is this related to another service?
No response
Describe the feature you'd like to request
Feature Request: Generic Help Panel Component for Amplify UI
Summary
Add a reusable, contextual help panel component to @aws-amplify/ui-react that can be integrated into any Amplify application to provide contextual help content.
Motivation
Currently, Amplify applications lack a standardized way to provide contextual help to users. Developers often need to build custom help systems or rely on external documentation links, leading to:
- Inconsistent UX across Amplify applications
- Development overhead for implementing help systems
- Poor discoverability of help content
- Context switching when users need help (leaving the app to read docs)
Benefits
For Users
- Contextual help without leaving the application
- Consistent experience across all Amplify apps
- Accessible help content with keyboard navigation
- Mobile-friendly responsive design
For Developers
- Zero configuration - works with default content
- Easy integration with existing Amplify components
- Customizable content and styling
- TypeScript support with full type definitions
For Amplify Ecosystem
- Improved onboarding for new users
- Reduced support burden with self-service help
- Consistent UX patterns across Amplify applications
- Enhanced accessibility compliance
Demo
A working demo is available showing:
- Contextual help content changes
- Interactive toggle functionality
- Responsive design
- Custom styling options
Testing
Comprehensive test suite included:
- Unit tests for all components
- Accessibility tests (a11y)
- Integration tests with Amplify components
- Cross-browser compatibility tests
Documentation
- Complete API documentation
- Integration examples with existing Amplify components
- Customization guides
- Accessibility guidelines
Breaking Changes
None - this is a new feature addition that doesn't modify existing APIs.
Implementation Plan
- Phase 1: Core components (HelpPanel, HelpContent, useHelpContext)
- Phase 2: Default help content for common scenarios
- Phase 3: Integration examples with existing Amplify components
- Phase 4: Documentation and migration guides
Questions for Maintainers
- Should this be part of
@aws-amplify/ui-reactor a separate package? - Any preferences for the default help content structure?
- Should we include integration hooks for existing components (StorageBrowser, Authenticator)?
- Any specific accessibility requirements beyond WCAG 2.1 AA?
Is this something the Amplify team would be interested in? I'm happy to implement this feature and would appreciate feedback on the proposed approach.
Describe the solution you'd like
Proposed Solution
A generic HelpPanel component that:
- Contextual: Automatically shows relevant help based on current view/action
- Reusable: Works with any Amplify UI component (Storage Browser, Authenticator, etc.)
- Customizable: Supports custom content, styling, and positioning
- Accessible: Built with ARIA attributes and keyboard navigation
- Zero-config: Works out of the box with sensible defaults
API Design
Basic Usage
import { HelpPanel } from '@aws-amplify/ui-react';
function MyApp() {
const [currentView, setCurrentView] = useState('storage-browser');
return (
<>
<StorageBrowser onViewChange={setCurrentView} />
<HelpPanel currentView={currentView} />
</>
);
}Advanced Usage
<HelpPanel
helpData={customHelpContent}
currentView="bucket-list"
currentAction="upload"
isOpen={helpOpen}
onToggle={setHelpOpen}
position="left"
customStyles={{ panel: { width: '500px' } }}
/>Components
Core Components
HelpPanel- Main panel component with toggle button and overlayHelpContent- Content renderer for help sections and linksuseHelpContext- Hook to determine contextual help based on view/action
Props Interface
interface HelpPanelProps {
helpData?: HelpContentData;
currentView?: string;
currentAction?: string;
isOpen?: boolean;
onToggle?: (isOpen: boolean) => void;
position?: 'left' | 'right';
customStyles?: CustomStyles;
}Implementation Details
File Structure
packages/ui-react/src/components/HelpPanel/
├── HelpPanel.tsx
├── HelpContent.tsx
├── index.ts
└── styles.css
packages/ui-react/src/hooks/
└── useHelpContext.ts
packages/ui-react/src/data/
└── helpContent.ts
Default Help Content
Includes help content for common Amplify scenarios:
- Storage Browser (bucket operations, file uploads)
- Authentication (sign in, sign up, password reset)
- Generic contexts (loading states, error handling)
Accessibility Features
- ARIA labels and roles
- Keyboard navigation (Tab, Escape, Enter)
- Focus management
- Screen reader compatibility
- High contrast support
Describe alternatives you've considered
Alternative Solutions Considered
- External documentation links - Poor UX, context switching
- Tooltips only - Limited content, not discoverable
- Modal dialogs - Intrusive, blocks main content
- Inline help text - Takes up valuable screen space
The proposed slide-out panel provides the best balance of discoverability, content capacity, and non-intrusive design.
Additional context
No response
Is this something that you'd be interested in working on?
- 👋 I may be able to implement this feature request
-
⚠️ This feature might incur a breaking change