Icon Widget Documentation

Overview​

The Icon widget is a visual component that displays scalable vector icons on your interface. It supports a wide variety of icon libraries and provides flexible styling options including color customization, size adjustment, and alignment controls.

Widget Properties​

Basic Configuration​

Icon Configuration​

Configuration Interface​

Global Section​

1. Name: Set a descriptive name for your icon widget
2. Variable/Model: Bind the widget to a data model variable if needed

Icon Properties​

1. Icon Selection:

   • Use the dropdown to select from available icons
   • Icons are displayed with preview in the selection list
   • Supports major icon libraries

2. Color Customization:

   • Click the color picker to choose icon color
   • Supports hex, RGB, and named colors
   • Real-time preview of color changes

3. Size Control:

   • Enter size value in pixels
   • Affects both width and height proportionally
   • Recommended range: 12px - 100px

4. Alignment Options:

   • Left: Aligns icon to the left side
   • Center: Centers the icon horizontally
   • Right: Aligns icon to the right side

Usage Examples​

Basic Icon Display​

// Simple warning icon
{
  name: "warning_icon",
  model: "status_icon",
  options: {
    icon: "fa fa-warning",
    color: "#ff9800",
    font: 24,
    align: "center"
  }
}

Status Indicator​

// Success status icon
{
  name: "success_indicator",
  model: "task_status",
  options: {
    icon: "fa fa-check-circle",
    color: "#4caf50",
    font: 18,
    align: "left"
  }
}

Navigation Icon​

// Menu navigation icon
{
  name: "menu_icon",
  model: "nav_menu",
  options: {
    icon: "fa fa-bars",
    color: "#333333",
    font: 20,
    align: "right"
  }
}

Styling Options​

Custom Classes​

• Add custom CSS classes through the Class field
• Use dynamic classes for conditional styling based on data

Responsive Design​

• Icons scale appropriately across different screen sizes
• Use relative units in custom CSS for better responsiveness

Color Schemes​

• Support for theme-based color schemes
• Can be integrated with global color variables

Validation and Visibility​

Screen-Based Validation​

Configure visibility and availability across different screens:

Advanced Conditions​

Use JavaScript expressions for dynamic visibility:

// Show icon only when status is active
{{status === 'active'}}

// Hide icon for certain user roles
{{user.role !== 'guest'}}

Integration with Data​

Model Binding​

While icons are primarily visual, they can be bound to data models for:

• Dynamic icon selection based on data values
• Conditional rendering based on status
• Integration with form validation states

Variable Usage​

// Dynamic icon based on status
icon: "{{status === 'success' ? 'fa fa-check' : 'fa fa-times'}}"

// Dynamic color based on priority
color: "{{priority === 'high' ? '#f44336' : '#2196f3'}}"

Icon Libraries​

Supported Libraries​

• Font Awesome: Comprehensive icon set with solid, regular, and brand icons
• Material Icons: Google's material design icons
• Custom Icon Fonts: Support for custom icon libraries

Icon Class Format​

/* Font Awesome */
fa fa-home
fa fa-user
fa fa-settings

/* Material Icons */
material-icons home
material-icons person
material-icons settings

Best Practices​

Performance​

1. Icon Selection: Choose appropriate icon sizes to maintain performance
2. Color Usage: Use CSS variables for consistent theming
3. Caching: Icon fonts are cached by browsers for better performance

Accessibility​

1. Alt Text: While icons don't have alt text, ensure surrounding context is clear
2. Color Contrast: Maintain sufficient contrast ratios for visibility
3. Size Guidelines: Use minimum 16px for important interactive icons

Design Consistency​

1. Icon Family: Use icons from the same library for consistency
2. Size Standards: Establish size guidelines (e.g., 16px, 20px, 24px)
3. Color Palette: Limit color variations to maintain visual hierarchy

Responsive Considerations​

1. Scalability: Test icons at different sizes and resolutions
2. Touch Targets: Ensure adequate spacing for mobile interfaces
3. Loading States: Consider placeholder or loading states for dynamic icons

Advanced Configuration​

Dynamic Properties​

All icon properties can be made dynamic using expressions:

{
  icon: "{{getIconByType(item.type)}}",
  color: "{{item.priority === 'high' ? '#ff0000' : '#666666'}}",
  font: "{{isMobile ? 18 : 24}}"
}

Event Handling​

While icons don't have built-in click handlers, they can be wrapped in clickable containers or used within interactive widgets.

Custom Styling​

/* Custom icon styles */
.custom-icon {
  text-shadow: 1px 1px 2px rgba(0,0,0,0.3);
  transition: all 0.3s ease;
}

.custom-icon:hover {
  transform: scale(1.1);
}

Troubleshooting​

Common Issues​

1. Icon Not Displaying:

   • Verify icon class name is correct
   • Check if icon library is loaded
   • Ensure icon font files are accessible

2. Size Not Applying:

   • Check for CSS conflicts
   • Verify font-size property inheritance
   • Use browser developer tools to inspect styles

3. Color Not Changing:

   • Ensure color property is properly formatted
   • Check for CSS specificity issues
   • Verify color value is valid

4. Alignment Issues:

   • Review container styles
   • Check for conflicting CSS rules
   • Ensure proper text-align inheritance

Debug Tips​

• Use browser developer tools to inspect icon elements
• Verify CSS class application
• Check console for any font loading errors
• Test with simple, known-working icon classes first