Syncfusion Blazor Inputs

Implementing Syncfusion Blazor FileUpload

This skill covers the Syncfusion Blazor FileUpload component, a robust solution for file handling in Blazor applications. Learn to implement single and multiple file uploads, configure validation rules, enable drag-drop interactions, handle large files with chunked uploads, and leverage comprehensive events for complete upload control and user feedback.

---

FileUpload

Learn to implement Syncfusion Blazor File Upload component with async/sync uploads, validation, events, customization, and always get immediate file handling with drag-drop or form integration for web and server applications.

Documentation

Getting Started

📄 Read: references/file-upload-getting-started.md

• Installation and NuGet package setup
• Visual Studio/Visual Studio Code setup steps
• Blazor WebAssembly vs Server configuration
• Basic SfUploader component rendering
• CSS and script imports
• Minimal working example

Core Configuration

📄 Read: references/file-upload-configuration.md

• ID property for component identification
• AllowedExtensions for file type restriction
• AllowMultiple vs single file uploads
• AutoUpload behavior configuration
• SequentialUpload for ordered processing
• DirectoryUpload capability
• Enabled state and component control

Upload Methods & Behavior

📄 Read: references/file-upload-file-upload-methods.md

• Synchronous vs asynchronous uploads
• Save URL and Remove URL configuration
• Upload button click handlers
• Automatic vs manual upload triggering
• Upload progress tracking mechanisms
• Backend API requirements

Events & Handlers

📄 Read: references/file-upload-events-and-handlers.md

• ValueChange event for direct file access (Blazor Server only, without AsyncSettings)
• FileSelected event for pre-validation
• Created event for initialization logic
• OnFileListRender for custom file display
• OnUploadStart, Success, OnFailure events (use with AsyncSettings)
• Event handler patterns and best practices
• Important: ValueChange and UploaderAsyncSettings are mutually exclusive

File Validation

📄 Read: references/file-upload-validation.md

• File type validation strategies
• File size constraints (MinFileSize, MaxFileSize)
• Custom validation functions
• Preventing invalid file uploads
• Error messages and user feedback
• Validation within EditForm

Advanced Features

📄 Read: references/file-upload-advanced-features.md

• Chunked upload for large files
• Pause and resume functionality
• Async/await patterns in event handlers
• MemoryStream processing without disk I/O
• Batch upload operations
• Retry and recovery mechanisms

Customization & Styling

📄 Read: references/file-upload-customization.md

• Custom file list templates
• CSS class customization
• Theme Studio integration
• Custom button styling
• Dark mode support
• Responsive design patterns

File Source Options

📄 Read: references/file-upload-file-source-options.md

• Drag-and-drop upload implementation
• Form integration patterns
• Direct file picker interaction
• Browser file dialog usage
• Directory selection and upload
• Multiple input method combinations
• Accessibility best practices

Localization & Accessibility

📄 Read: references/file-upload-localization-accessibility.md

• Multi-language UI support
• Locale configuration options
• Custom text labels
• WCAG 2.1 compliance
• Keyboard navigation implementation
• Screen reader support
• ARIA attributes

Platform-Specific Setup

📄 Read: references/file-upload-platform-specific-setup.md

• Blazor WebAssembly app setup
• Blazor Server app setup
• Blazor Web App (.NET 8+) setup
• MAUI integration
• Different render modes
• Platform-specific considerations

Quick Start Example

@using Syncfusion.Blazor.Inputs

<SfUploader AutoUpload="true" AllowedExtensions=".jpg,.jpeg,.png,.pdf">
    <UploaderAsyncSettings 
        SaveUrl="api/upload/save" 
        RemoveUrl="api/upload/remove">
    </UploaderAsyncSettings>
</SfUploader>

Common Patterns

Pattern 1: Basic File Upload with Validation (Server Upload)

• Use AutoUpload="true" for instant uploads
• Configure UploaderAsyncSettings with SaveUrl/RemoveUrl
• Set AllowedExtensions to restrict file types
• Listen to FileSelected event for pre-validation
• Use Success/OnFailure events for upload feedback

Pattern 2: Direct File Access (Blazor Server Only)

• Use ValueChange event to access file content directly
• Do NOT use UploaderAsyncSettings with ValueChange
• Process files in memory or save to directory
• Best for file preview, Base64 conversion, or direct storage

Pattern 3: Multiple File Handling

• Set AllowMultiple="true" to allow batch uploads
• Use SequentialUpload for ordered processing
• Track progress with upload events
• Display file list with individual progress indicators

Pattern 4: Large File Upload with Chunking

• Configure ChunkSize in UploaderAsyncSettings
• Enable pause/resume with chunk upload
• Implement retry logic for failed chunks
• Show chunk-level progress to user

Key Props

Common Use Cases

1. Document Upload: Resume, PDF, certification file uploads 2. Image Gallery: User profile pictures, photo collections 3. Data Import: CSV/Excel file imports for data processing 4. Media Library: Video, audio file uploads and management 5. Backup Uploads: Database backups, configuration files 6. Report Generation: Monthly reports, analytics data 7. Invoice Processing: Financial document uploads 8. User Attachments: Email attachments, message files

Quick Decision Tree

User needs file upload functionality ├─ Single file only? → Set AllowMultiple="false" + use basic setup ├─ Multiple files? │ ├─ All at once? → AllowMultiple="true" + SequentialUpload="false" │ └─ One at a time? → AllowMultiple="true" + SequentialUpload="true" └─ Large files (>100MB)? ├─ Enable chunking → Set ChunkSize property └─ Add pause/resume → Listen to Paused and OnResume events

---

TextArea

Learn to implement Syncfusion Blazor TextArea component for multi-line text input with configurable resize modes, row/column sizing, character limits, floating labels, and comprehensive validation. Perfect for comments, descriptions, messages, and any scenario requiring extended text entry with real-time feedback and form integration.

Documentation

Getting Started

📄 Read: references/textarea-getting-started.md

• Installation and NuGet package setup
• Basic SfTextArea component setup
• Namespace imports and service registration
• CSS theme configuration
• Minimal working example
• Initial component rendering

Configuration Options

📄 Read: references/textarea-configuration.md

• RowCount and ColumnCount for sizing
• ResizeMode (Vertical, Horizontal, Both, None)
• MaxLength property for character limits
• Placeholder text configuration
• FloatLabelType (Auto, Always, Never)
• ReadOnly and Disabled states
• Width property and responsive sizing
• HTML attributes customization

Events and Data Binding

📄 Read: references/textarea-events-binding.md

• Value property and two-way binding (@bind-Value)
• ValueChange event for real-time updates
• Focus and Blur events (TextAreaFocusInEventArgs, TextAreaFocusOutEventArgs)
• Input event for keystroke tracking
• Created and Destroyed lifecycle events
• Form validation integration with EditForm
• ValueExpression for validation binding

Customization and Styling

📄 Read: references/textarea-customization.md

• CssClass for custom styling
• ShowClearButton for quick text removal
• InputAttributes and HtmlAttributes
• Theme customization with Theme Studio
• Responsive design patterns
• Accessibility features (ARIA, keyboard navigation)
• RTL (Right-to-Left) support with EnableRtl

Quick Start Example

@using Syncfusion.Blazor.Inputs

<SfTextArea @bind-Value="@description"
            Placeholder="Enter description..."
            RowCount="5"
            ColumnCount="50"
            MaxLength="500"
            FloatLabelType="FloatLabelType.Auto">
</SfTextArea>

@code {
    private string description = "";
}

Common Patterns

Pattern 1: Basic Multi-Line Input

• Use RowCount to set visible lines (default: 2)
• Set Placeholder for user guidance
• Enable @bind-Value for two-way binding
• Apply MaxLength for character constraints

Pattern 2: Resizable TextArea with Limits

• Set ResizeMode="Resize.Both" for user resizing
• Configure RowCount and ColumnCount for initial size
• Use MaxLength to prevent excessive input
• Listen to ValueChange for live character counting

Pattern 3: Form Integration with Validation

• Wrap in <EditForm> with model binding
• Use @bind-Value with ValueExpression
• Apply [Required] or [StringLength] attributes
• Display validation messages with <ValidationMessage>
• Style invalid state with CSS

Pattern 4: Auto-Growing TextArea

• Set ResizeMode="Resize.Vertical" for vertical expansion
• Start with minimal RowCount (e.g., 3)
• Allow user to expand as needed
• Combine with MaxLength for upper bounds

Key Props

Common Use Cases

1. Comment Sections: User feedback, review comments, discussion threads 2. Form Descriptions: Product descriptions, bio sections, about fields 3. Message Composition: Email bodies, chat messages, note-taking 4. Code/JSON Input: Configuration files, script input, data entry 5. Address Fields: Multi-line address entry with street, city, etc. 6. Search Queries: Complex search inputs with multiple criteria 7. Customer Support: Ticket descriptions, issue reporting, help requests 8. Content Management: Article drafts, blog post editing, documentation

Quick Decision Tree

User needs multi-line text input ├─ Fixed size? → Set ResizeMode="Resize.None" + specific RowCount ├─ User-resizable? │ ├─ Vertical only? → ResizeMode="Resize.Vertical" │ ├─ Horizontal only? → ResizeMode="Resize.Horizontal" │ └─ Both directions? → ResizeMode="Resize.Both" ├─ Character limit needed? → Set MaxLength property └─ Form validation? ├─ Use within <EditForm> └─ Add ValueExpression for validation binding

---

Signature

Learn to implement Syncfusion Blazor Signature component for capturing digital signatures with configurable stroke width, colors, background images, save/load functionality in multiple formats (PNG, JPEG, SVG), and comprehensive event handling. Perfect for e-signatures, document approval workflows, digital consent forms, and any scenario requiring handwritten signature capture with touch and mouse support.

Documentation

Getting Started

📄 Read: references/signature-getting-started.md

• Installation and NuGet package setup
• Basic SfSignature component setup
• Namespace imports and service registration
• CSS theme configuration
• Canvas rendering and initialization
• Touch and mouse input support
• Minimal working example

Drawing Configuration

📄 Read: references/signature-drawing-configuration.md

• MinStrokeWidth and MaxStrokeWidth for pen thickness
• StrokeColor for ink color customization
• BackgroundColor for canvas background
• BackgroundImage for letterhead/watermark
• Velocity property for stroke smoothness
• Drawing behavior and responsiveness
• Pressure sensitivity simulation

Save and Load Signatures

📄 Read: references/signature-save-load.md

• Save() method with format options (PNG, JPEG, SVG)
• SaveWithBackground property configuration
• GetSignature() for Base64 string retrieval
• Load() method for existing signatures
• Clear() method for signature removal
• File format selection and quality settings
• Server integration patterns
• Database storage strategies

Event Handling

📄 Read: references/signature-events.md

• Changed event for stroke tracking
• OnSave event for save operations
• Created event for initialization
• Event argument structure
• Real-time signature validation
• Detecting empty vs filled signatures
• Event-driven workflows

Customization and Styling

📄 Read: references/signature-customization.md

• Disabled and IsReadOnly states
• HtmlAttributes for custom styling
• Canvas size customization
• Theme integration
• Mobile and touch device optimization
• Accessibility considerations
• Responsive design patterns

Quick Start Example

@using Syncfusion.Blazor.Inputs

<div class="signature-container">
    <label>Sign below:</label>
    <SfSignature @ref="signatureRef"
                 StrokeColor="#000000"
                 BackgroundColor="#FFFFFF"
                 MaxStrokeWidth="2.0"
                 MinStrokeWidth="0.5">
    </SfSignature>
    
    <div class="signature-actions">
        <button @onclick="SaveSignature">Save</button>
        <button @onclick="ClearSignature">Clear</button>
    </div>
</div>

@code {
    private SfSignature signatureRef;
    
    private async Task SaveSignature()
    {
        await signatureRef.SaveAsync(SignatureFileType.Png, "signature.png");
    }
    
    private async Task ClearSignature()
    {
        await signatureRef.ClearAsync();
    }
}

Common Patterns

Pattern 1: Basic Signature Capture

• Use default stroke settings for natural handwriting feel
• Set BackgroundColor="#FFFFFF" for clear canvas
• Provide Clear button for user corrections
• Save as PNG for universal compatibility
• Validate signature is not empty before submission

Pattern 2: Document Signing with Letterhead

• Use BackgroundImage for company letterhead or form template
• Set SaveWithBackground="true" to include background in saved file
• Configure StrokeColor to contrast with background
• Save as PNG or JPEG with background embedded
• Ideal for contracts, agreements, official documents

Pattern 3: Mobile-Optimized Signature

• Increase stroke width for better touch visibility
• Use larger canvas size for thumb-friendly drawing
• Set IsReadOnly="false" only when signature mode active
• Auto-save on signature completion
• Provide clear visual feedback for touch interactions

Pattern 4: Multi-Signature Forms

• Use multiple SfSignature components for different signatories
• Track completion state per signature field
• Save each signature with unique identifier
• Combine signatures in final document generation
• Validate all required signatures before form submission

Key Props

Common Use Cases

1. E-Signature Capture: Digital document signing, contract approval, consent forms 2. Financial Services: Loan applications, account opening, transaction authorization 3. Healthcare: Patient consent forms, HIPAA agreements, medical records 4. Legal Documents: Contracts, NDAs, legal agreements, court documents 5. HR Processes: Employment contracts, onboarding documents, policy acknowledgments 6. Delivery Confirmation: Package delivery signatures, service completion 7. Check-In Systems: Visitor logs, attendance tracking, registration forms 8. Educational: Test proctoring, form submissions, parent consent

Quick Decision Tree

User needs signature capture ├─ Basic signature? │ └─ Use default settings + Save as PNG ├─ Document with letterhead? │ ├─ Set BackgroundImage property │ └─ Enable SaveWithBackground="true" ├─ Mobile/touch primary? │ ├─ Increase MaxStrokeWidth to 3.0+ │ └─ Use larger canvas dimensions ├─ Multiple signers? │ ├─ Use multiple SfSignature components │ ├─ Track each signature state separately │ └─ Save with unique identifiers └─ Need specific format? ├─ PNG → Universal support, transparency ├─ JPEG → Smaller file size, no transparency └─ SVG → Vector format, scalable

---

RangeSlider

Learn to implement Syncfusion Blazor Range Slider component with dual handles for range selection, ticks, tooltips, color ranges, movement limits, and always get immediate two-value selection for price filters, date ranges, temperature zones, or any scenario requiring range input with visual feedback and validation in Blazor applications.

Documentation

Getting Started

📄 Read: references/rangeslider-getting-started.md

• Installation and NuGet package setup
• Basic SfSlider with Type="SliderType.Range"
• Value binding with arrays for dual handles
• CSS imports and theme configuration
• Namespace imports and service registration
• Minimal working example with range selection

Range Configuration

📄 Read: references/rangeslider-range-configuration.md

• Min, Max, and Step properties for range bounds
• Type property (SliderType.Range vs Default)
• Two-way value binding with arrays (@bind-Value)
• Custom non-numeric values with CustomValues
• IsImmediateValue for real-time updates
• Value array structure and data types

Ticks and Tooltip

📄 Read: references/rangeslider-ticks-and-tooltip.md

• SliderTicks component configuration
• LargeStep and SmallStep for interval markers
• Tick placement options (Before, After, Both)
• ShowSmallTicks property for granular display
• Format property for tick label customization
• SliderTooltip component setup
• Tooltip visibility modes (Focus, Hover, Always, Auto)
• Tooltip placement and format customization
• Custom tooltip templates

Color Ranges and Visual Indication

📄 Read: references/rangeslider-color-ranges-visual.md

• SliderColorRanges for visual feedback
• ColorRange components with Start, End, Color
• Multiple color segments for different value zones
• Use cases (temperature zones, price tiers, ratings)
• Color customization and styling
• Accessibility considerations for color choices

Limits and Constraints

📄 Read: references/rangeslider-limits-and-constraints.md

• SliderLimits configuration for movement restrictions
• MinStart, MinEnd, MaxStart, MaxEnd properties
• Enabled property for limit activation
• StartHandleFixed and EndHandleFixed for locked handles
• Restricting handle movement within bounds
• Use cases (booking date ranges, budget constraints)
• Validation patterns with limits

Orientation and Customization

📄 Read: references/rangeslider-orientation-and-customization.md

• Orientation property (Horizontal vs Vertical)
• ShowButtons for increment/decrement controls
• Width property for responsive sizing
• EnableAnimation for smooth transitions
• CssClass for custom styling
• EnableRtl for right-to-left language support
• ReadOnly and Enabled states
• Theme customization with Theme Studio

Events and Data Binding

📄 Read: references/rangeslider-events-and-binding.md

• SliderEvents component configuration
• ValueChange event callback for range updates
• OnChange vs Changed event timing
• Created event for initialization logic
• Rendered event for post-render operations
• OnTooltipChange for dynamic tooltip content
• OnTicksRender for custom tick label rendering
• Form integration with EditForm
• Validation with EditContext and data annotations

Quick Start Example

@using Syncfusion.Blazor.Inputs

<div class="range-slider-container">
    <label>Select Price Range: $@priceRange[0] - $@priceRange[1]</label>
    <SfSlider @bind-Value="@priceRange"
              Type="SliderType.Range"
              Min="0"
              Max="1000"
              Step="10">
        <SliderTicks Placement="Placement.After" LargeStep="200" SmallStep="50" ShowSmallTicks="true"></SliderTicks>
        <SliderTooltip IsVisible="true" ShowOn="TooltipShowOn.Always" Format="C0"></SliderTooltip>
    </SfSlider>
</div>

@code {
    private int[] priceRange = new int[] { 200, 800 };
}

Common Patterns

Pattern 1: Basic Range Selection

• Set Type="SliderType.Range" for dual handles
• Bind value to int[] or double[] array with two elements
• Configure Min, Max, and Step properties
• Enable tooltip with IsVisible="true" for user feedback
• Use ValueChange event to capture range updates

Pattern 2: Range with Visual Color Zones

• Add SliderColorRanges component
• Define multiple ColorRange segments (e.g., cold/warm/hot)
• Set colors that provide clear visual distinction
• Use for temperature, ratings, or risk indicators
• Combine with ticks for precise value identification

Pattern 3: Constrained Range Selection

• Use SliderLimits to restrict handle movement
• Set MinStart/MaxStart for first handle bounds
• Set MinEnd/MaxEnd for second handle bounds
• Enable StartHandleFixed or EndHandleFixed if one handle should be locked
• Ideal for booking systems, budget planning, scheduling

Pattern 4: Custom Value Range Selection

• Use CustomValues array for non-numeric ranges
• Example: string[] { "XS", "S", "M", "L", "XL", "XXL" }
• Value array uses indices, not actual values
• Display custom labels via tick formatting
• Perfect for size selection, priority levels, skill ratings

Key Props

Common Use Cases

1. E-Commerce Price Filters: Min/max price selection, budget range filtering 2. Date Range Pickers: Check-in/check-out dates, event duration, scheduling 3. Temperature Control: HVAC systems, oven settings, climate zones 4. Age Range Selection: Demographics, target audience, age restrictions 5. Time Range Selection: Working hours, availability slots, time windows 6. Score/Rating Ranges: Grade filtering, performance metrics, review scores 7. Financial Planning: Budget allocation, investment ranges, spending limits 8. Resource Allocation: CPU/memory limits, bandwidth throttling, capacity planning

Quick Decision Tree

User needs range selection (two values) ├─ Numeric range? │ ├─ Set Type="SliderType.Range" │ ├─ Use int[] or double[] for Value │ └─ Configure Min, Max, Step ├─ Non-numeric values (sizes, labels)? │ ├─ Set CustomValues array │ ├─ Value array contains indices │ └─ Use tick formatting for labels ├─ Need visual zones? │ ├─ Add SliderColorRanges component │ └─ Define multiple ColorRange segments ├─ Restrict movement? │ ├─ Use SliderLimits component │ ├─ Set MinStart/MaxStart/MinEnd/MaxEnd │ └─ Enable StartHandleFixed or EndHandleFixed if needed ├─ Vertical layout needed? │ └─ Set Orientation="SliderOrientation.Vertical" └─ Real-time updates during drag? └─ Set IsImmediateValue="true"

---

OtpInput

Learn to implement Syncfusion Blazor OtpInput (One-Time Password) component for secure verification code entry with configurable length, input types (number, text, password), styling modes (outlined, underlined, filled), automatic focus management, and comprehensive event handling. Perfect for 2FA authentication, email verification, SMS codes, PIN entry, and any scenario requiring secure multi-digit code input with keyboard navigation and accessibility support.

Documentation

Getting Started

📄 Read: references/otpinput-getting-started.md

• Installation and NuGet package setup
• Basic SfOtpInput component setup
• Namespace imports and service registration
• CSS theme configuration
• Length property for OTP digit count
• Value binding and retrieval
• Minimal working example

Configuration Options

📄 Read: references/otpinput-configuration.md

• Length property for digit count (default: 4)
• Type property (Number, Text, Password)
• Placeholder configuration for empty inputs
• Separator for visual grouping
• AutoFocus for immediate input
• Disabled state management
• ID and HtmlAttributes customization

Styling Modes

📄 Read: references/otpinput-styling-modes.md

• StylingMode options (Outlined, Underlined, Filled)
• TextTransform (None, Lowercase, Uppercase)
• CssClass for custom styling
• Theme customization with Theme Studio
• Responsive design patterns
• Visual states and focus indicators

Events and Data Binding

📄 Read: references/otpinput-events-binding.md

• Value property and two-way binding (@bind-Value)
• ValueChanged event callback (use Value property only, NOT @bind-Value)
• OnInput event with OtpInputEventArgs
• OnFocus and OnBlur events
• Created lifecycle event
• Form validation integration
• Real-time verification patterns
• Auto-submit on completion

Accessibility

📄 Read: references/otpinput-accessibility.md

• AriaLabels array for individual input fields
• Keyboard navigation (arrows, backspace, delete)
• Screen reader support
• WCAG 2.1 compliance
• Focus management best practices
• Password type accessibility considerations
• Mobile device optimization

Quick Start Example

@using Syncfusion.Blazor.Inputs

<div class="otp-container">
    <label>Enter verification code:</label>
    <SfOtpInput @bind-Value="@otpValue"
                Length="6"
                Type="OtpInputType.Number"
                StylingMode="OtpInputStyle.Outlined">
    </SfOtpInput>
    
    @if (!string.IsNullOrEmpty(message))
    {
        <div class="message">@message</div>
    }
</div>

@code {
    private string otpValue = "";
    private string message = "";
    
    protected override void OnParametersSet()
    {
        if (otpValue.Length == 6)
        {
            message = "Verifying code...";
            // Call verification API
        }
    }
}

Common Patterns

Pattern 1: Basic OTP Verification (6-digit numeric)

• Set Length="6" for standard OTP length
• Use Type="OtpInputType.Number" for numeric-only input
• Enable AutoFocus="true" for immediate input
• Use @bind-Value for two-way binding (simplest approach)
• Validate and verify OTP on server

Pattern 2: Email/SMS Verification Code

• Configure Length="4" or Length="6" based on service
• Use Type="OtpInputType.Number" for numeric codes
• Set StylingMode="OtpInputStyle.Underlined" for clean look
• Auto-focus first input on page load
• Show countdown timer for code expiration
• Provide "Resend code" functionality

Pattern 3: Secure PIN Entry

• Use Type="OtpInputType.Password" to mask input
• Set Length="4" or Length="6" for PIN length
• Apply StylingMode="OtpInputStyle.Filled" for modern look
• Implement rate limiting for security
• Clear input on failed attempts
• Show visual feedback for validation

Pattern 4: Alphanumeric Verification (with separators)

• Set Type="OtpInputType.Text" for letters and numbers
• Use TextTransform="TextTransform.Uppercase" for readability
• Configure Separator="-" to visually group digits
• Example: ABC-123-XYZ pattern
• Set Length="9" (including separator positions)
• Useful for activation codes, license keys

Key Props

Common Use Cases

1. Two-Factor Authentication (2FA): Login security, account verification, multi-factor authentication 2. Email Verification: Account activation, email confirmation, newsletter signup 3. SMS Verification: Phone number verification, mobile app login, transaction confirmation 4. Password Reset: Secure password recovery, account access restoration 5. Transaction Verification: Banking transactions, payment confirmation, fund transfers 6. Access Control: Building entry codes, secure area access, temporary access codes 7. Device Pairing: Bluetooth pairing codes, smart device setup, IoT device linking 8. Activation Codes: Software licenses, product activation, subscription validation

Quick Decision Tree

User needs OTP/verification code input ├─ Numeric only? │ ├─ Set Type="OtpInputType.Number" │ └─ Use Length="4" or Length="6" ├─ Need to hide input (PIN)? │ ├─ Set Type="OtpInputType.Password" │ └─ Apply security best practices ├─ Alphanumeric codes? │ ├─ Set Type="OtpInputType.Text" │ ├─ Use TextTransform="TextTransform.Uppercase" │ └─ Consider Separator for readability ├─ Auto-submit when complete? │ ├─ Listen to ValueChanged event │ ├─ Check if value.Length == Length │ └─ Call verification API automatically ├─ Custom styling needed? │ ├─ Outlined → StylingMode="OtpInputStyle.Outlined" (default) │ ├─ Underlined → StylingMode="OtpInputStyle.Underlined" │ └─ Filled → StylingMode="OtpInputStyle.Filled" └─ Accessibility important? ├─ Set AriaLabels array for screen readers └─ Enable AutoFocus for keyboard users

---

Rating

Learn to implement Syncfusion Blazor Rating component for intuitive rating and feedback collection with configurable precision modes (full, half, quarter, exact), custom icons and templates, label and tooltip support, comprehensive event handling, and accessibility features. Perfect for product reviews, skill assessments, satisfaction surveys, quality ratings, and any scenario requiring user feedback through star ratings or custom iconography with keyboard navigation and form integration.

Documentation

Getting Started

📄 Read: references/rating-getting-started.md

• Installation and NuGet package setup
• Basic SfRating component setup
• Namespace imports and service registration
• CSS theme configuration
• ItemsCount property for rating scale
• Value binding and retrieval
• Minimal working example
• Basic 5-star rating implementation

Precision and Values

📄 Read: references/rating-precision-and-values.md

• Precision property (Full, Half, Quarter, Exact)
• Full precision for whole numbers only
• Half precision for 0.5 increments
• Quarter precision for 0.25 increments
• Exact precision for decimal values
• Min property for minimum rating value
• AllowReset for clearing ratings
• EnableSingleSelection for single-item mode
• Value calculations and display

Labels and Tooltips

📄 Read: references/rating-labels-and-tooltips.md

• ShowLabel property for label display
• LabelPosition (Top, Bottom, Left, Right)
• LabelTemplate for custom label formatting
• ShowTooltip property for hover tooltips
• TooltipTemplate for custom tooltip content
• Dynamic label updates based on value
• Contextual feedback patterns

Templates and Customization

📄 Read: references/rating-templates-customization.md

• EmptyTemplate for unselected items
• FullTemplate for selected items
• RatingItemContext for template data
• Custom icon implementation (hearts, thumbs, emojis)
• SVG and icon font integration
• CssClass for custom styling
• EnableAnimation property
• Theme customization and responsive design

Events and States

📄 Read: references/rating-events-and-states.md

• ValueChanged event for rating updates
• OnItemHover event with RatingHoverEventArgs
• Created lifecycle event
• Form validation integration
• ReadOnly state for display-only ratings
• Disabled state management
• Visible property control
• Keyboard navigation support
• Accessibility features and ARIA attributes

Quick Start Example

@using Syncfusion.Blazor.Inputs

<div class="rating-container">
    <label>Rate your experience:</label>
    <SfRating @bind-Value="@userRating"
              ItemsCount="5"
              Precision="PrecisionType.Full"
              ShowLabel="true">
    </SfRating>
    
    @if (userRating > 0)
    {
        <p>You rated: @userRating / 5 stars</p>
    }
</div>

@code {
    private double userRating = 0;
}

Common Patterns

Pattern 1: Basic 5-Star Product Rating

• Use default ItemsCount="5" for standard rating
• Set Precision="PrecisionType.Full" for whole stars only
• Enable @bind-Value for two-way data binding
• Show ShowLabel="true" to display rating value
• Position label with LabelPosition="LabelPosition.Right"
• Use ValueChanged event for auto-submit

Pattern 2: Half-Star Rating with Hover Feedback

• Set Precision="PrecisionType.Half" for 0.5 increments
• Enable ShowTooltip="true" for hover feedback
• Use OnItemHover event for preview
• Display average ratings with ReadOnly="true"
• Show rating count in custom label template
• Implement real-time feedback messages

Pattern 3: Custom Icon Templates (Hearts, Thumbs, Emojis)

• Define EmptyTemplate for unselected state
• Define FullTemplate for selected state
• Use RatingItemContext for item-specific rendering
• Implement custom icons (♥, 👍, 😊, etc.)
• Apply CssClass for custom colors and sizing
• Enable EnableAnimation="true" for smooth transitions

Pattern 4: Multi-Category Rating Form

• Create multiple SfRating components
• Different ItemsCount per category if needed
• Combine with EditForm for validation
• Calculate overall rating average
• Track completion with event handlers
• Enable submit only when all ratings complete

Key Props

Common Use Cases

1. Product Reviews: E-commerce ratings, marketplace feedback, customer reviews, product quality assessment 2. Service Quality: Restaurant ratings, hotel reviews, delivery service feedback, support satisfaction 3. Skill Assessments: Employee evaluations, competency ratings, training feedback, proficiency levels 4. Content Rating: Article feedback, video ratings, course reviews, documentation usefulness 5. User Experience: App store ratings, feature satisfaction, usability scores, NPS surveys 6. Performance Reviews: Team member evaluations, project ratings, goal achievements, KPI tracking 7. Survey Responses: Satisfaction surveys, opinion polls, feedback forms, questionnaires 8. Quality Control: Inspection ratings, compliance scoring, audit results, quality metrics 9. Entertainment: Movie ratings, music reviews, book ratings, game scores 10. Sentiment Analysis: Customer sentiment, brand perception, mood tracking, emotional feedback

Quick Decision Tree

User needs rating/feedback functionality ├─ Display existing rating (read-only)? │ ├─ Set ReadOnly="true" │ ├─ Use Precision="PrecisionType.Exact" for average ratings │ └─ Show ShowLabel="true" with review count ├─ Collect new rating from user? │ ├─ Whole stars only? → Precision="PrecisionType.Full" │ ├─ Half stars? → Precision="PrecisionType.Half" │ ├─ Quarter stars? → Precision="PrecisionType.Quarter" │ └─ Any decimal? → Precision="PrecisionType.Exact" ├─ Custom rating scale? │ ├─ 3-point scale → ItemsCount="3" │ ├─ 7-point scale → ItemsCount="7" │ └─ 10-point scale → ItemsCount="10" ├─ Need custom icons instead of stars? │ ├─ Hearts → Define EmptyTemplate and FullTemplate with ♥ │ ├─ Thumbs → Use 👍/👎 icons │ ├─ Emojis → Use 😞😐🙂😊🤩 progression │ └─ Custom SVG → Render SVG in templates ├─ Thumbs up/down only? │ ├─ Set EnableSingleSelection="true" │ ├─ Use ItemsCount="1" or ItemsCount="2" │ └─ Custom templates with thumb icons ├─ Form integration needed? │ ├─ Use within <EditForm> │ ├─ Add validation attributes │ └─ Listen to ValueChanged for validation ├─ Show rating feedback? │ ├─ Enable ShowLabel="true" for numeric display │ ├─ Use LabelTemplate for custom messages │ ├─ Enable ShowTooltip="true" for hover feedback │ └─ Use TooltipTemplate for contextual messages └─ Accessibility requirements? ├─ Ensure keyboard navigation works (arrow keys) ├─ Test screen reader compatibility └─ Provide clear ARIA labels

---

InputMask

Learn to implement Syncfusion Blazor InputMask (MaskedTextBox) component for formatted text input with predefined patterns, custom mask rules, prompt characters, and always get immediate masked input for phone numbers, SSN, credit cards, dates, ZIP codes, license plates, or any scenario requiring structured text entry with format validation, literal preservation, and comprehensive event handling in Blazor applications.

Documentation

Getting Started

📄 Read: references/inputmask-getting-started.md

• Installation and NuGet package setup
• Basic SfMaskedTextBox component setup
• Namespace imports and service registration
• CSS theme configuration
• Simple mask examples (phone, date, SSN)
• Value binding basics
• Minimal working example

Mask Patterns and Configuration

📄 Read: references/inputmask-mask-patterns.md

• Standard mask characters (0, 9, L, ?, A, &, C, #)
• Predefined patterns (phone, SSN, ZIP, date, time)
• Mask property configuration
• Literal characters in masks
• Optional vs required positions
• Complex pattern examples
• International format patterns
• Pattern validation rules

Custom Characters and Formatting

📄 Read: references/inputmask-custom-characters.md

• CustomCharacters dictionary usage
• Creating custom mask rules
• Regex-based character validation
• Advanced pattern customization
• Use cases (license plates, product codes, etc.)
• Combining custom with standard masks
• Best practices for custom rules

Prompt Character Configuration

📄 Read: references/inputmask-prompt-configuration.md

• PromptChar property (default: _)
• PromptPlaceholder for display
• EnableLiterals for value inclusion
• Placeholder vs PromptChar difference
• Visual feedback configuration
• User experience considerations
• Examples with different configurations

Events and Data Binding

📄 Read: references/inputmask-events-binding.md

• Value property and @bind-Value
• ValueChange event (MaskChangeEventArgs)
• ValueChanged event callback
• Focus and Blur events (MaskFocusEventArgs, MaskBlurEventArgs)
• OnChange vs OnInput vs ValueChange timing
• EditForm integration with EditContext
• ValueExpression for validation
• Real-time validation patterns
• Event handler best practices

Styling and Accessibility

📄 Read: references/inputmask-styling-accessibility.md

• FloatLabelType configuration
• ShowClearButton functionality
• CssClass for custom styling
• Width and responsive sizing
• Enabled vs Readonly states
• Theme customization with Theme Studio
• WCAG 2.1 compliance
• Keyboard navigation
• ARIA attributes
• Screen reader support
• RTL (EnableRtl) support
• HtmlAttributes and InputAttributes
• Accessibility best practices

Quick Start Example

@using Syncfusion.Blazor.Inputs

<div class="input-mask-container">
    <label>Phone Number:</label>
    <SfMaskedTextBox @bind-Value="@phoneNumber"
                     Mask="(000) 000-0000"
                     Placeholder="Enter phone number"
                     FloatLabelType="FloatLabelType.Auto">
    </SfMaskedTextBox>
    
    <label>Social Security Number:</label>
    <SfMaskedTextBox @bind-Value="@ssn"
                     Mask="000-00-0000"
                     PromptChar="#"
                     Placeholder="Enter SSN">
    </SfMaskedTextBox>
</div>

@code {
    private string phoneNumber = "";
    private string ssn = "";
}

Common Patterns

Pattern 1: Phone Number Input (US Format)

• Use mask "(000) 000-0000" for US phone numbers
• Set PromptChar="_" for clear visual feedback
• Enable @bind-Value for two-way binding
• Use FloatLabelType.Auto for modern UX
• Configure Placeholder for user guidance
• Set EnableLiterals="false" to exclude parentheses/dashes from value

Pattern 2: Social Security Number (SSN)

• Use mask "000-00-0000" for SSN format
• Set PromptChar="#" or PromptChar="*" for privacy
• Apply Readonly="false" for input, Readonly="true" for display
• Use ShowClearButton="true" for quick reset
• Implement validation with ValueChange event
• Consider masking display value for security

Pattern 3: Credit Card Number with Separators

• Use mask "0000 0000 0000 0000" for 16-digit cards
• Set EnableLiterals="false" to get digits only
• Listen to ValueChange to detect card type (Visa, MC, Amex)
• Show card brand icon based on first digits
• Apply real-time Luhn algorithm validation
• Use PromptChar="X" for clear empty positions

Pattern 4: Date Input with Custom Format

• Use mask "00/00/0000" for MM/DD/YYYY format
• Or "00-00-0000" for DD-MM-YYYY format
• Set Placeholder="MM/DD/YYYY" for format guidance
• Implement custom validation for valid dates
• Use ValueChange to validate day/month ranges
• Consider using DatePicker component for complex date selection

Pattern 5: Custom Product Code Format

• Define CustomCharacters dictionary for special rules
• Example: @(new Dictionary<string, string> { { "P", "[A-Z]" }, { "N", "[0-9]" } })
• Use mask like "PPP-NNN-NNN" for ABC-123-456 format
• Combine standard and custom characters
• Apply TextTransform for uppercase conversion
• Validate against business rules in events

Pattern 6: International Phone with Custom Characters

• Use CustomCharacters for country-specific patterns
• Example: "+00 (000) 000-0000" with country code
• Set EnableLiterals="true" to include + and formatting
• Display country flag based on code
• Implement dynamic mask switching per country
• Support multiple international formats

Key Props

Common Use Cases

1. Contact Information: Phone numbers, fax numbers, mobile numbers with country codes 2. Personal Identification: SSN, tax ID, national ID, passport numbers, driver's license 3. Financial Data: Credit card numbers, bank account numbers, routing numbers, CVV codes 4. Dates and Times: Custom date formats, time entry, date ranges with specific patterns 5. Postal Codes: ZIP codes (US), postal codes (international), area codes with formatting 6. Product Identification: SKU numbers, serial numbers, product codes, barcode entry 7. License Numbers: Vehicle plates, software licenses, registration numbers with patterns 8. Network Information: IP addresses, MAC addresses, subnet masks with dot notation 9. Version Numbers: Software versions (1.2.3), build numbers with custom formats 10. Custom Codes: Voucher codes, promo codes, tracking numbers with specific patterns

Quick Decision Tree

User needs formatted text input with pattern ├─ Standard formats? │ ├─ US Phone → Mask="(000) 000-0000" │ ├─ SSN → Mask="000-00-0000" │ ├─ ZIP Code → Mask="00000" or Mask="00000-0000" │ ├─ Credit Card → Mask="0000 0000 0000 0000" │ ├─ Date → Mask="00/00/0000" (MM/DD/YYYY) │ └─ Time → Mask="00:00" (HH:MM) ├─ Need digits only in value? │ ├─ Set EnableLiterals="false" │ └─ Mask literals will be excluded from Value ├─ Include formatting in value? │ ├─ Set EnableLiterals="true" (default) │ └─ Value will include parentheses, dashes, etc. ├─ Custom pattern (not standard)? │ ├─ Use CustomCharacters dictionary │ ├─ Define regex for each custom character │ ├─ Example: { "P", "[A-Z]" } for uppercase letters │ └─ Combine in mask: "PPP-000-NNN" ├─ Privacy/security concerns? │ ├─ Set PromptChar="*" or PromptChar="#" │ ├─ Use Readonly="true" for display-only masked data │ └─ Implement additional masking on display if needed ├─ International format support? │ ├─ Use CustomCharacters for flexible patterns │ ├─ Implement dynamic mask switching based on locale │ └─ Consider country/region selection ├─ Form validation needed? │ ├─ Use within <EditForm> with model binding │ ├─ Add ValueExpression for validation │ ├─ Apply data annotations ([Required], [StringLength]) │ ├─ Listen to ValueChange for real-time validation │ └─ Implement custom validation logic (Luhn, date ranges) ├─ Enhance user experience? │ ├─ Set FloatLabelType="FloatLabelType.Auto" │ ├─ Enable ShowClearButton="true" for quick reset │ ├─ Use meaningful Placeholder text │ └─ Provide visual feedback on validation └─ Accessibility important? ├─ Ensure keyboard navigation works ├─ Set proper ARIA labels via HtmlAttributes ├─ Test screen reader compatibility └─ Provide clear format instructions in label/placeholder

---

ColorPicker

Learn to implement Syncfusion Blazor ColorPicker component for intuitive color selection with picker and palette modes, opacity control, preset color collections, inline or popup display, mode switching, and always get immediate color input for themes, UI customization, design tools, data visualization, branding, or any scenario requiring color selection with hex/rgba values, recent colors tracking, and comprehensive event handling in Blazor applications.

Documentation

Getting Started

📄 Read: references/colorpicker-getting-started.md

• Installation and NuGet package setup
• Basic SfColorPicker component setup
• Namespace imports and service registration
• CSS theme configuration
• Value binding with color formats
• Mode overview (Picker vs Palette)
• Minimal working example

Modes and Configuration

📄 Read: references/colorpicker-modes-configuration.md

• ColorPickerMode (Picker vs Palette)
• Picker mode for gradient color selection
• Palette mode for predefined color grids
• Inline vs Popup display options
• ModeSwitcher for user mode selection
• Columns configuration for palette layout
• ShowButtons for Apply/Cancel actions
• Mode-specific behaviors and use cases

Preset Colors and Palettes

📄 Read: references/colorpicker-presets-colors.md

• PresetColors dictionary configuration
• Custom color palette groups
• Default preset color collections
• ShowRecentColors functionality
• NoColor option for "no selection"
• Organizing preset categories
• Business and design use cases

Opacity and Value Formats

📄 Read: references/colorpicker-opacity-values.md

• EnableOpacity for alpha channel control
• Opacity slider configuration
• Value formats (hex, rgba, hsva)
• Reading and setting opacity values
• Transparent color handling
• Use cases (overlays, highlights, transparency)

Events and Data Binding

📄 Read: references/colorpicker-events-binding.md

• Value property and two-way binding (@bind-Value)
• ValueChanged event callback
• Selected event with ColorPickerEventArgs
• OnOpen and OnClose events for popup control
• ModeSwitched event handling
• OnTileRender for custom palette tiles
• Form integration with EditForm
• Real-time color preview patterns

Customization and Accessibility

📄 Read: references/colorpicker-customization-accessibility.md

• ShowButtons configuration
• CssClass for custom styling
• Disabled and EnableRtl states
• HtmlAttributes customization
• Keyboard navigation support
• ARIA attributes for accessibility
• WCAG 2.1 compliance
• Theme customization with Theme Studio
• Responsive design patterns

Quick Start Example

@using Syncfusion.Blazor.Inputs

<div class="colorpicker-container">
    <label>Choose a color:</label>
    <SfColorPicker @bind-Value="@selectedColor"
                   Mode="ColorPickerMode.Palette"
                   ShowButtons="true">
    </SfColorPicker>
    
    <div class="color-preview" style="background-color: @selectedColor;">
        Selected: @selectedColor
    </div>
</div>

@code {
    private string selectedColor = "#008000";
}

Common Patterns

Pattern 1: Basic Palette Color Picker

• Use Mode="ColorPickerMode.Palette" for predefined color grid
• Enable @bind-Value for two-way binding
• Set ShowButtons="true" for Apply/Cancel actions
• Use default PresetColors or customize
• Bind to string variable for hex values
• Display preview with selected color

Pattern 2: Advanced Gradient Picker with Opacity

• Set Mode="ColorPickerMode.Picker" for gradient selector
• Enable EnableOpacity="true" for alpha channel
• Use ModeSwitcher="true" to allow mode switching
• Display rgba value for transparency
• Ideal for design tools, graphics editors
• Show real-time preview with opacity

Pattern 3: Inline Color Selector (No Popup)

• Set Inline="true" for always-visible picker
• Use for color customization panels
• No popup trigger, immediate display
• Works with both Picker and Palette modes
• Combine with ShowButtons="false" for instant selection
• Perfect for settings panels, theme builders

Pattern 4: Custom Preset Palette

• Define PresetColors dictionary with custom groups
• Organize by categories (brand colors, pastels, etc.)
• Set Columns property for grid layout
• Use ShowRecentColors="true" for history
• Enable NoColor="true" for "no selection" option
• Ideal for brand color systems, design systems

Key Props

Common Use Cases

1. UI Theme Customization: User-selectable themes, color scheme builders, personalization 2. Design Tools: Graphic editors, drawing apps, image annotation, markup tools 3. Data Visualization: Chart color selection, graph customization, report styling 4. Branding: Logo colors, brand identity, style guide implementation, corporate colors 5. Web Design: CSS color selection, background colors, text colors, border colors 6. Product Customization: Product color variants, custom merchandise, personalization 7. Highlighting Tools: Text highlighters, annotation colors, emphasis markers 8. Dashboard Customization: Widget colors, status indicators, category colors 9. Form Builders: Custom form styling, input colors, validation colors 10. Calendar/Scheduling: Event colors, category coding, priority indicators

Quick Decision Tree

User needs color selection functionality ├─ Specific predefined colors only? │ ├─ Use Mode="ColorPickerMode.Palette" │ ├─ Set PresetColors with custom palette │ └─ Configure Columns for grid layout ├─ Any color from gradient? │ ├─ Use Mode="ColorPickerMode.Picker" (default) │ └─ Users can select from full color spectrum ├─ Allow both modes? │ ├─ Enable ModeSwitcher="true" │ └─ Users can toggle between Picker and Palette ├─ Need transparency/opacity? │ ├─ Set EnableOpacity="true" │ ├─ Value will include alpha (rgba format) │ └─ Show opacity slider for user control ├─ Always visible (no popup)? │ ├─ Set Inline="true" │ ├─ Use in settings panels, sidebars │ └─ Consider ShowButtons="false" for instant selection ├─ Popup with confirmation? │ ├─ Use Inline="false" (default) │ ├─ Set ShowButtons="true" for Apply/Cancel │ └─ Listen to Selected event for confirmed selection ├─ Track recent colors? │ ├─ Enable ShowRecentColors="true" (default) │ └─ Recent colors displayed automatically ├─ Allow "no color" selection? │ ├─ Set NoColor="true" │ └─ User can clear color selection ├─ Custom color palette needed? │ ├─ Define PresetColors dictionary │ ├─ Group colors by category │ └─ Example: { "Basic": ["#fff", "#000"], "Brand": ["#e74c3c", "#3498db"] } ├─ Form integration required? │ ├─ Use within <EditForm> │ ├─ Apply validation attributes │ └─ Listen to ValueChanged for validation └─ Accessibility important? ├─ Ensure keyboard navigation works (Tab, Enter, Escape) ├─ Test screen reader compatibility └─ Provide clear labels via HtmlAttributes

ColorPicker - Customization and Accessibility

Table of Contents

• Overview
• ShowButtons Configuration
• Custom Styling with CssClass
• Component States
• HtmlAttributes Customization
• Keyboard Navigation
• ARIA Attributes
• WCAG Compliance
• Theme Customization
• Responsive Design
• Best Practices

Overview

The ColorPicker component provides extensive customization options and built-in accessibility features including:

• Custom CSS styling
• Disabled and RTL states
• Keyboard navigation support
• ARIA attributes for screen readers
• WCAG 2.1 compliance
• Theme Studio integration
• Responsive design patterns

ShowButtons Configuration

Control Apply and Cancel buttons visibility in popup mode.

With Buttons (Confirmation Required)

<SfColorPicker @bind-Value="@color" 
               ShowButtons="true">
</SfColorPicker>

@code {
    private string color = "#3498db";
}

Features:

• Apply button confirms selection
• Cancel button reverts to previous value
• User must explicitly confirm
• Better for significant changes

Without Buttons (Immediate Selection)

<SfColorPicker @bind-Value="@color" 
               ShowButtons="false">
</SfColorPicker>

@code {
    private string color = "#e74c3c";
}

Features:

• Immediate color selection
• No confirmation needed
• Faster interaction
• Better for exploratory use

Custom Styling with CssClass

Apply custom CSS classes for tailored appearance.

Basic Custom Styling

<SfColorPicker @bind-Value="@color" 
               CssClass="custom-picker">
</SfColorPicker>

@code {
    private string color = "#2ecc71";
}

<style>
    .custom-picker .e-split-btn-wrapper {
        border: 2px solid #3498db;
        border-radius: 8px;
    }
    
    .custom-picker .e-selected-color {
        border-radius: 6px;
    }
</style>

Themed Color Picker

<SfColorPicker @bind-Value="@color" 
               CssClass="dark-picker">
</SfColorPicker>

@code {
    private string color = "#9b59b6";
}

<style>
    .dark-picker {
        background-color: #2c3e50;
    }
    
    .dark-picker .e-split-btn-wrapper {
        background-color: #34495e;
        border: 1px solid #7f8c8d;
    }
    
    .dark-picker .e-color-picker-tooltip {
        background-color: #34495e;
        color: #ecf0f1;
    }
</style>

Size Variations

<div class="size-examples">
    <h4>Small</h4>
    <SfColorPicker @bind-Value="@color1" CssClass="small-picker"></SfColorPicker>
    
    <h4>Medium (Default)</h4>
    <SfColorPicker @bind-Value="@color2"></SfColorPicker>
    
    <h4>Large</h4>
    <SfColorPicker @bind-Value="@color3" CssClass="large-picker"></SfColorPicker>
</div>

@code {
    private string color1 = "#3498db";
    private string color2 = "#e74c3c";
    private string color3 = "#2ecc71";
}

<style>
    .small-picker .e-split-btn-wrapper {
        width: 60px;
        height: 30px;
    }
    
    .large-picker .e-split-btn-wrapper {
        width: 100px;
        height: 50px;
    }
</style>

Custom Button Styling

<SfColorPicker @bind-Value="@color" 
               CssClass="rounded-picker"
               ShowButtons="true">
</SfColorPicker>

@code {
    private string color = "#f39c12";
}

<style>
    .rounded-picker .e-split-btn-wrapper {
        border-radius: 25px;
    }
    
    .rounded-picker .e-btn {
        border-radius: 20px;
        padding: 8px 20px;
    }
    
    .rounded-picker .e-apply {
        background-color: #27ae60;
        border-color: #27ae60;
    }
    
    .rounded-picker .e-cancel {
        background-color: #e74c3c;
        border-color: #e74c3c;
    }
</style>

Component States

Disabled State

<SfColorPicker @bind-Value="@color" 
               Disabled="@isDisabled">
</SfColorPicker>

<button @onclick="() => isDisabled = !isDisabled">
    @(isDisabled ? "Enable" : "Disable")
</button>

@code {
    private string color = "#1abc9c";
    private bool isDisabled = false;
}

Conditional Disabling

<SfColorPicker @bind-Value="@backgroundColor" 
               Disabled="@(!allowCustomization)">
</SfColorPicker>

<label>
    <input type="checkbox" @bind="allowCustomization" />
    Allow Color Customization
</label>

@code {
    private string backgroundColor = "#ecf0f1";
    private bool allowCustomization = true;
}

EnableRtl (Right-to-Left)

<SfColorPicker @bind-Value="@color" 
               EnableRtl="true">
</SfColorPicker>

@code {
    private string color = "#e67e22";
}

Use for:

• Arabic language interfaces
• Hebrew language interfaces
• Other RTL languages
• Mirrored layouts

EnablePersistence

<SfColorPicker @bind-Value="@color" 
               EnablePersistence="true"
               ID="persistentPicker">
</SfColorPicker>

@code {
    private string color = "#16a085";
}

Features:

• Maintains state across page reloads
• Stores color selection in browser
• Requires unique ID property
• Useful for user preferences

HtmlAttributes Customization

Add custom HTML attributes to the wrapper element.

Basic HTML Attributes

<SfColorPicker @bind-Value="@color" 
               HtmlAttributes="@customAttributes">
</SfColorPicker>

@code {
    private string color = "#c0392b";
    
    private Dictionary<string, object> customAttributes = new Dictionary<string, object>
    {
        { "data-color-type", "theme-primary" },
        { "aria-label", "Primary theme color selector" },
        { "title", "Select a color for the primary theme" }
    };
}

Tooltip with Title Attribute

<SfColorPicker @bind-Value="@color" 
               HtmlAttributes="@tooltipAttributes">
</SfColorPicker>

@code {
    private string color = "#8e44ad";
    
    private Dictionary<string, object> tooltipAttributes = new Dictionary<string, object>
    {
        { "title", "Click to choose a color" },
        { "data-toggle", "tooltip" }
    };
}

Data Attributes for Testing

<SfColorPicker @bind-Value="@color" 
               HtmlAttributes="@testAttributes">
</SfColorPicker>

@code {
    private string color = "#27ae60";
    
    private Dictionary<string, object> testAttributes = new Dictionary<string, object>
    {
        { "data-testid", "brand-color-picker" },
        { "data-component", "colorpicker" },
        { "data-required", "true" }
    };
}

Keyboard Navigation

The ColorPicker supports comprehensive keyboard navigation.

Keyboard Shortcuts

Keyboard Navigation Example

@page "/keyboard-accessible-picker"
@using Syncfusion.Blazor.Inputs

<h3>Keyboard Accessible Color Selection</h3>

<p>Try navigating with keyboard:</p>
<ul>
    <li>Tab to reach the color picker</li>
    <li>Press Space or Enter to open</li>
    <li>Use arrow keys to navigate colors</li>
    <li>Press Enter to select</li>
    <li>Press Escape to cancel</li>
</ul>

<div class="form-group">
    <label for="picker1">Primary Color:</label>
    <SfColorPicker @bind-Value="@primaryColor" 
                   ID="picker1"
                   Mode="ColorPickerMode.Palette">
    </SfColorPicker>
</div>

<div class="form-group">
    <label for="picker2">Secondary Color:</label>
    <SfColorPicker @bind-Value="@secondaryColor" 
                   ID="picker2"
                   Mode="ColorPickerMode.Palette">
    </SfColorPicker>
</div>

@code {
    private string primaryColor = "#3498db";
    private string secondaryColor = "#e74c3c";
}

Focus Management

<SfColorPicker @bind-Value="@color" 
               CssClass="focus-visible">
</SfColorPicker>

@code {
    private string color = "#2ecc71";
}

<style>
    .focus-visible .e-split-btn-wrapper:focus {
        outline: 3px solid #3498db;
        outline-offset: 2px;
    }
    
    .focus-visible .e-tile:focus {
        box-shadow: 0 0 0 3px rgba(52, 152, 219, 0.5);
    }
</style>

ARIA Attributes

Built-in ARIA attributes for screen reader support.

Accessible Label

<div class="form-field">
    <label id="colorLabel">Background Color:</label>
    <SfColorPicker @bind-Value="@color" 
                   HtmlAttributes="@ariaAttributes">
    </SfColorPicker>
</div>

@code {
    private string color = "#f39c12";
    
    private Dictionary<string, object> ariaAttributes = new Dictionary<string, object>
    {
        { "aria-labelledby", "colorLabel" },
        { "aria-describedby", "colorHelp" }
    };
}

ARIA Live Region for Changes

<SfColorPicker @bind-Value="@color" 
               ValueChange="@AnnounceColorChange">
</SfColorPicker>

<div aria-live="polite" aria-atomic="true" class="sr-only">
    @screenReaderAnnouncement
</div>

@code {
    private string color = "#9b59b6";
    private string screenReaderAnnouncement = "";
    
    private void AnnounceColorChange(ColorPickerEventArgs args)
    {
        screenReaderAnnouncement = $"Color changed to {args.CurrentValue.Hex}";
        StateHasChanged();
    }
}

<style>
    .sr-only {
        position: absolute;
        width: 1px;
        height: 1px;
        padding: 0;
        margin: -1px;
        overflow: hidden;
        clip: rect(0,0,0,0);
        white-space: nowrap;
        border-width: 0;
    }
</style>

WCAG Compliance

Ensure ColorPicker meets WCAG 2.1 accessibility standards.

Sufficient Color Contrast

<div class="accessible-color-selector">
    <label for="textColor">Text Color:</label>
    <SfColorPicker @bind-Value="@textColor" 
                   ID="textColor"
                   ValueChange="@ValidateContrast">
    </SfColorPicker>
    
    <label for="bgColor">Background Color:</label>
    <SfColorPicker @bind-Value="@bgColor" 
                   ID="bgColor"
                   ValueChange="@ValidateContrast">
    </SfColorPicker>
    
    <div class="contrast-info" role="status" aria-live="polite">
        @if (!string.IsNullOrEmpty(contrastMessage))
        {
            <p class="@contrastClass">@contrastMessage</p>
        }
    </div>
    
    <div class="preview" style="color: @textColor; background-color: @bgColor; padding: 20px;">
        Sample Text - Check Contrast
    </div>
</div>

@code {
    private string textColor = "#000000";
    private string bgColor = "#ffffff";
    private string contrastMessage = "";
    private string contrastClass = "";
    
    private void ValidateContrast(ColorPickerEventArgs args)
    {
        // Simplified contrast check (real implementation would calculate luminance ratio)
        double ratio = CalculateContrastRatio(textColor, bgColor);
        
        if (ratio >= 7.0)
        {
            contrastMessage = $"Excellent contrast ratio: {ratio:F1}:1 (AAA)";
            contrastClass = "success";
        }
        else if (ratio >= 4.5)
        {
            contrastMessage = $"Good contrast ratio: {ratio:F1}:1 (AA)";
            contrastClass = "success";
        }
        else
        {
            contrastMessage = $"Poor contrast ratio: {ratio:F1}:1 - May not meet WCAG standards";
            contrastClass = "warning";
        }
    }
    
    private double CalculateContrastRatio(string color1, string color2)
    {
        // Simplified mock calculation
        return 4.5; // Real implementation would calculate actual luminance ratio
    }
}

<style>
    .contrast-info .success { color: #27ae60; }
    .contrast-info .warning { color: #e67e22; }
</style>

Required Field Indication

<div class="form-group">
    <label for="requiredColor">
        Brand Color <span class="required" aria-label="required">*</span>
    </label>
    <SfColorPicker @bind-Value="@brandColor" 
                   ID="requiredColor"
                   HtmlAttributes="@requiredAttributes">
    </SfColorPicker>
</div>

@code {
    private string brandColor = "#3498db";
    
    private Dictionary<string, object> requiredAttributes = new Dictionary<string, object>
    {
        { "aria-required", "true" }
    };
}

<style>
    .required {
        color: #e74c3c;
        font-weight: bold;
    }
</style>

Theme Customization

Theme Studio Integration

The ColorPicker integrates with Syncfusion Theme Studio for custom themes.

Steps: 1. Visit Theme Studio 2. Customize ColorPicker appearance 3. Download generated CSS 4. Include in your application

Custom Theme Example

<link href="custom-theme.css" rel="stylesheet" />

<SfColorPicker @bind-Value="@color" 
               CssClass="custom-theme">
</SfColorPicker>

@code {
    private string color = "#e74c3c";
}

Dark Mode Support

<SfColorPicker @bind-Value="@color" 
               CssClass="@(isDarkMode ? "dark-mode-picker" : "")">
</SfColorPicker>

<button @onclick="ToggleDarkMode">Toggle Dark Mode</button>

@code {
    private string color = "#2ecc71";
    private bool isDarkMode = false;
    
    private void ToggleDarkMode()
    {
        isDarkMode = !isDarkMode;
    }
}

<style>
    .dark-mode-picker {
        filter: invert(1) hue-rotate(180deg);
    }
    
    /* Or with custom dark theme */
    .dark-mode-picker .e-color-picker-container {
        background-color: #2c3e50;
        color: #ecf0f1;
    }
</style>

Responsive Design

Mobile-Friendly Configuration

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Palette"
               Columns="@GetResponsiveColumns()"
               CssClass="responsive-picker">
</SfColorPicker>

@code {
    private string color = "#f39c12";
    
    [Inject]
    private NavigationManager NavigationManager { get; set; }
    
    private int GetResponsiveColumns()
    {
        // Simplified - real implementation would check window size
        return 5; // Use 5 columns for mobile
    }
}

Adaptive Layout

@page "/responsive-colorpicker"
@using Syncfusion.Blazor.Inputs

<div class="color-selector-container">
    <h3>Responsive Color Picker</h3>
    
    <!-- Desktop: Inline display -->
    <div class="desktop-only">
        <SfColorPicker @bind-Value="@color" 
                       Inline="true"
                       Mode="ColorPickerMode.Palette"
                       Columns="10">
        </SfColorPicker>
    </div>
    
    <!-- Mobile: Popup display with fewer columns -->
    <div class="mobile-only">
        <SfColorPicker @bind-Value="@color" 
                       Inline="false"
                       Mode="ColorPickerMode.Palette"
                       Columns="5">
        </SfColorPicker>
    </div>
</div>

@code {
    private string color = "#3498db";
}

<style>
    .mobile-only {
        display: none;
    }
    
    @@media (max-width: 768px) {
        .desktop-only {
            display: none;
        }
        
        .mobile-only {
            display: block;
        }
    }
</style>

Best Practices

Accessibility Checklist

• ✅ Provide clear labels for all color pickers
• ✅ Ensure keyboard navigation works completely
• ✅ Include ARIA attributes for screen readers
• ✅ Announce color changes to assistive technologies
• ✅ Validate color contrast for readability
• ✅ Support focus indicators
• ✅ Test with screen readers (NVDA, JAWS, VoiceOver)
• ✅ Ensure touch targets are 44x44px minimum (mobile)
• ✅ Don't rely solely on color to convey information

Customization Best Practices

1. Consistent styling: Match your app's design system 2. Performance: Minimize custom CSS complexity 3. Responsive: Test on various screen sizes 4. Dark mode: Support system dark mode preference 5. Testing: Validate on multiple browsers 6. Documentation: Document custom CSS classes 7. Maintenance: Keep custom styles separate and organized 8. Accessibility: Never compromise accessibility for aesthetics

Common Customization Patterns

/* Minimal modern look */
.modern-picker .e-split-btn-wrapper {
    border: none;
    border-radius: 8px;
    box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}

/* Bordered with shadow */
.bordered-picker .e-split-btn-wrapper {
    border: 2px solid #3498db;
    box-shadow: 0 4px 6px rgba(52, 152, 219, 0.2);
}

/* Compact size */
.compact-picker .e-split-btn-wrapper {
    width: 50px;
    height: 28px;
}

/* Full-width on mobile */
@@media (max-width: 768px) {
    .responsive-picker .e-split-btn-wrapper {
        width: 100%;
    }
}

Related Topics

• Getting Started: Initial setup → colorpicker-getting-started.md
• Events: Event handling → colorpicker-events-binding.md
• Presets: Custom palettes → colorpicker-presets-colors.md

ColorPicker - Events and Data Binding

Table of Contents

• Overview
• Value Binding
• ValueChange Event
• Selected Event
• OnOpen and OnClose Events
• ModeSwitched Event
• OnTileRender Event
• Form Integration
• Real-Time Preview Patterns

Overview

The ColorPicker component provides comprehensive event handling for:

• Value changes and selection confirmation
• Popup open/close events
• Mode switching tracking
• Custom palette tile rendering
• Form validation integration
• Real-time color preview

Value Binding

Two-Way Binding

<SfColorPicker @bind-Value="@selectedColor">
</SfColorPicker>

<p>Selected Color: @selectedColor</p>

@code {
    private string selectedColor = "#3498db";
}

One-Way Binding with Event

<SfColorPicker Value="@currentColor" 
               ValueChange="@OnColorChanged">
</SfColorPicker>

<p>Current Color: @currentColor</p>

@code {
    private string currentColor = "#e74c3c";
    
    private void OnColorChanged(ColorPickerEventArgs args)
    {
        currentColor = args.CurrentValue.Hex;
        Console.WriteLine($"Color changed to: {currentColor}");
    }
}

Binding to Object Property

<SfColorPicker @bind-Value="@theme.PrimaryColor">
</SfColorPicker>

<p>Theme Primary Color: @theme.PrimaryColor</p>

@code {
    private ThemeSettings theme = new ThemeSettings { PrimaryColor = "#3498db" };
    
    public class ThemeSettings
    {
        public string PrimaryColor { get; set; }
        public string SecondaryColor { get; set; }
    }
}

ValueChange Event

Fires when the color value changes (immediate on selection or on Apply button click if ShowButtons="true").

Basic ValueChange Handler

<SfColorPicker @bind-Value="@color" 
               ValueChange="@OnValueChanged">
</SfColorPicker>

<div class="log">
    <p>Last changed: @lastChanged</p>
</div>

@code {
    private string color = "#008000";
    private string lastChanged = "Not yet";
    
    private void OnValueChanged(ColorPickerEventArgs args)
    {
        lastChanged = DateTime.Now.ToString("HH:mm:ss");
        Console.WriteLine($"New color: {args.CurrentValue.Hex}");
    }
}

ColorPickerEventArgs Properties

<SfColorPicker @bind-Value="@color" 
               ValueChange="@OnColorChange"
               EnableOpacity="true">
</SfColorPicker>

<div class="color-info">
    <p>Hex: @colorInfo.Hex</p>
    <p>RGBA: @colorInfo.Rgba</p>
</div>

@code {
    private string color = "rgba(52, 152, 219, 0.8)";
    private ColorInfo colorInfo = new ColorInfo();
    
    private void OnColorChange(ColorPickerEventArgs args)
    {
        colorInfo.Hex = args.CurrentValue.Hex;
        colorInfo.Rgba = args.CurrentValue.Rgba;
    }
    
    private class ColorInfo
    {
        public string Hex { get; set; }
        public string Rgba { get; set; }
    }
}

Async ValueChanged Handler

<SfColorPicker @bind-Value="@themeColor" 
               ValueChange="@OnThemeColorChanged">
</SfColorPicker>

<p>Status: @saveStatus</p>

@code {
    private string themeColor = "#2ecc71";
    private string saveStatus = "Ready";
    
    private async Task OnThemeColorChanged(ColorPickerEventArgs args)
    {
        saveStatus = "Saving...";
        
        // Save to database or API
        await SaveThemeColorAsync(args.CurrentValue.Hex);
        
        saveStatus = "Saved!";
        
        // Reset status after delay
        await Task.Delay(2000);
        saveStatus = "Ready";
    }
    
    private async Task SaveThemeColorAsync(string color)
    {
        // Simulate API call
        await Task.Delay(500);
        Console.WriteLine($"Saved color: {color}");
    }
}

Selected Event

Fires when user confirms selection (with Apply button or immediate selection).

Basic Selected Handler

<SfColorPicker @bind-Value="@color" 
               ShowButtons="true"
               Selected="@OnColorSelected">
</SfColorPicker>

<p>Confirmed Color: @confirmedColor</p>

@code {
    private string color = "#9b59b6";
    private string confirmedColor = "None";
    
    private void OnColorSelected(ColorPickerEventArgs args)
    {
        confirmedColor = args.CurrentValue.Hex;
        Console.WriteLine($"User confirmed: {confirmedColor}");
    }
}

Selected vs ValueChange

<SfColorPicker @bind-Value="@color" 
               ShowButtons="true"
               ValueChange="@OnValueChanged"
               Selected="@OnSelected">
</SfColorPicker>

<div class="event-log">
    <p>ValueChanged: @valueChangeCount times</p>
    <p>Selected: @selectedCount times</p>
</div>

@code {
    private string color = "#f39c12";
    private int valueChangeCount = 0;
    private int selectedCount = 0;
    
    private void OnValueChanged(ColorPickerEventArgs args)
    {
        valueChangeCount++;
        Console.WriteLine("ValueChanged fired");
    }
    
    private void OnSelected(ColorPickerEventArgs args)
    {
        selectedCount++;
        Console.WriteLine("Selected fired - User clicked Apply");
    }
}

Difference:

• ValueChange: Fires on every color change (including preview)
• Selected: Fires only on Apply button click (if ShowButtons="true") or final selection

OnOpen and OnClose Events

Track popup open and close events.

Open Event

<SfColorPicker @bind-Value="@color" 
               OnOpen="@OnPickerOpen">
</SfColorPicker>

<p>Opened: @openCount times</p>

@code {
    private string color = "#1abc9c";
    private int openCount = 0;
    
    private void OnPickerOpen(BeforeOpenCloseEventArgs args)
    {
        openCount++;
        Console.WriteLine("ColorPicker opened");
        
        // Can cancel opening
        // args.Cancel = true;
    }
}

Close Event

<SfColorPicker @bind-Value="@color" 
               OnClose="@OnPickerClose">
</SfColorPicker>

<p>Closed: @closeCount times</p>

@code {
    private string color = "#e67e22";
    private int closeCount = 0;
    
    private void OnPickerClose(BeforeOpenCloseEventArgs args)
    {
        closeCount++;
        Console.WriteLine("ColorPicker closed");
        
        // Can cancel closing
        // args.Cancel = true;
    }
}

Conditional Open/Close

<SfColorPicker @bind-Value="@color" 
               OnOpen="@OnBeforeOpen"
               OnClose="@OnBeforeClose">
</SfColorPicker>

<button @onclick="() => allowInteraction = !allowInteraction">
    @(allowInteraction ? "Lock" : "Unlock") Picker
</button>

@code {
    private string color = "#16a085";
    private bool allowInteraction = true;
    
    private void OnBeforeOpen(BeforeOpenCloseEventArgs args)
    {
        if (!allowInteraction)
        {
            args.Cancel = true;
            Console.WriteLine("Opening prevented - Picker locked");
        }
    }
    
    private void OnBeforeClose(BeforeOpenCloseEventArgs args)
    {
        // Could validate selection before closing
        if (string.IsNullOrEmpty(color))
        {
            args.Cancel = true;
            Console.WriteLine("Closing prevented - No color selected");
        }
    }
}

Opened Event (After Opening)

<SfColorPicker @bind-Value="@color" 
               Opened="@OnPickerOpened">
</SfColorPicker>

@code {
    private string color = "#c0392b";
    
    private void OnPickerOpened(OpenEventArgs args)
    {
        Console.WriteLine("ColorPicker has opened (after animation)");
        // Can perform actions after popup is fully displayed
    }
}

PopupClosed Event

<SfColorPicker @bind-Value="@color" 
               PopupClosed="@OnPopupClosed">
</SfColorPicker>

@code {
    private string color = "#8e44ad";
    
    private void OnPopupClosed(Object args)
    {
        Console.WriteLine("Popup has closed completely");
        // Cleanup or logging after popup closes
    }
}

ModeSwitched Event

Tracks when user switches between Picker and Palette modes.

Basic ModeSwitched Handler

<SfColorPicker @bind-Value="@color" 
               ModeSwitcher="true"
               ModeSwitched="@OnModeSwitch">
</SfColorPicker>

<p>Current Mode: @currentMode</p>

@code {
    private string color = "#2ecc71";
    private string currentMode = "Picker";
    
    private void OnModeSwitch(ModeSwitchEventArgs args)
    {
        currentMode = args.Mode.ToString();
        Console.WriteLine($"Switched to: {currentMode}");
    }
}

Track Mode Preferences

<SfColorPicker @bind-Value="@color" 
               ModeSwitcher="true"
               OnModeSwitch="@OnModeChange">
</SfColorPicker>

<div class="stats">
    <p>Picker Mode Used: @pickerUsage times</p>
    <p>Palette Mode Used: @paletteUsage times</p>
</div>

@code {
    private string color = "#f1c40f";
    private int pickerUsage = 0;
    private int paletteUsage = 0;
    
    private void OnModeChange(ModeSwitchEventArgs args)
    {
        if (args.Mode == ColorPickerMode.Picker)
            pickerUsage++;
        else
            paletteUsage++;
    }
}

OnTileRender Event

Customize palette tiles before rendering.

Custom Tile Styling

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Palette"
               OnTileRender="@OnTileRenderHandler">
</SfColorPicker>

@code {
    private string color = "#3498db";
    
    private void OnTileRenderHandler(PaletteTileEventArgs args)
    {
        // Add custom class to specific colors
        if (args.Value == "#e74c3c")
        {
            args.Element.AddClass("favorite-color");
        }
        
        // Add tooltip
        args.Element.SetAttribute("title", $"Color: {args.Value}");
    }
}

Mark Popular Colors

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Palette"
               OnTileRender="@MarkPopularColors">
</SfColorPicker>

@code {
    private string color = "#9b59b6";
    private List<string> popularColors = new List<string> { "#3498db", "#e74c3c", "#2ecc71" };
    
    private void MarkPopularColors(PaletteTileEventArgs args)
    {
        if (popularColors.Contains(args.Value))
        {
            args.Element.AddClass("popular-tile");
            args.Element.SetAttribute("title", "Popular Color");
        }
    }
}

<style>
    .popular-tile {
        border: 2px solid gold !important;
        box-shadow: 0 0 5px rgba(255, 215, 0, 0.5);
    }
</style>

Form Integration

EditForm with Validation

<EditForm Model="@formModel" OnValidSubmit="@HandleSubmit">
    <DataAnnotationsValidator />
    
    <div class="form-group">
        <label>Brand Color:</label>
        <SfColorPicker @bind-Value="@formModel.BrandColor" 
                       Mode="ColorPickerMode.Palette">
        </SfColorPicker>
        <ValidationMessage For="@(() => formModel.BrandColor)" />
    </div>
    
    <div class="form-group">
        <label>Accent Color:</label>
        <SfColorPicker @bind-Value="@formModel.AccentColor" 
                       EnableOpacity="true">
        </SfColorPicker>
        <ValidationMessage For="@(() => formModel.AccentColor)" />
    </div>
    
    <button type="submit">Save Theme</button>
</EditForm>

@code {
    private ThemeFormModel formModel = new ThemeFormModel();
    
    private void HandleSubmit()
    {
        Console.WriteLine($"Brand: {formModel.BrandColor}, Accent: {formModel.AccentColor}");
        // Save to database
    }
    
    public class ThemeFormModel
    {
        [Required(ErrorMessage = "Brand color is required")]
        public string BrandColor { get; set; } = "#3498db";
        
        [Required(ErrorMessage = "Accent color is required")]
        public string AccentColor { get; set; } = "rgba(231, 76, 60, 0.8)";
    }
}

Custom Validation

<EditForm Model="@colorForm" OnValidSubmit="@OnSubmit">
    <div class="form-group">
        <label>Background Color:</label>
        <SfColorPicker @bind-Value="@colorForm.BackgroundColor" 
                       ValueChange="@ValidateContrast">
        </SfColorPicker>
    </div>
    
    <div class="form-group">
        <label>Text Color:</label>
        <SfColorPicker @bind-Value="@colorForm.TextColor" 
                       ValueChange="@ValidateContrast">
        </SfColorPicker>
    </div>
    
    @if (!string.IsNullOrEmpty(validationMessage))
    {
        <div class="alert alert-warning">@validationMessage</div>
    }
    
    <button type="submit" disabled="@(!isValid)">Apply Colors</button>
</EditForm>

@code {
    private ColorFormModel colorForm = new ColorFormModel();
    private string validationMessage = "";
    private bool isValid = true;
    
    private void ValidateContrast(ColorPickerEventArgs args)
    {
        // Simplified contrast check
        bool bgIsLight = IsLightColor(colorForm.BackgroundColor);
        bool textIsLight = IsLightColor(colorForm.TextColor);
        
        if (bgIsLight == textIsLight)
        {
            validationMessage = "Warning: Poor contrast between background and text colors";
            isValid = false;
        }
        else
        {
            validationMessage = "";
            isValid = true;
        }
    }
    
    private bool IsLightColor(string color)
    {
        // Simplified lightness check (would need proper implementation)
        return color.Contains("255") || color.Contains("fff");
    }
    
    private void OnSubmit()
    {
        if (isValid)
        {
            Console.WriteLine($"Colors applied: BG={colorForm.BackgroundColor}, Text={colorForm.TextColor}");
        }
    }
    
    public class ColorFormModel
    {
        public string BackgroundColor { get; set; } = "#ffffff";
        public string TextColor { get; set; } = "#000000";
    }
}

Real-Time Preview Patterns

Live Background Update

@page "/live-background"
@using Syncfusion.Blazor.Inputs

<div class="config-panel">
    <h3>Choose Background Color</h3>
    <SfColorPicker @bind-Value="@bgColor" 
                   EnableOpacity="true"
                   ValueChange="@OnBackgroundChange">
    </SfColorPicker>
</div>

<div class="preview-area" style="background-color: @bgColor; min-height: 300px; padding: 40px; transition: background-color 0.3s ease;">
    <h2 style="color: white; text-shadow: 2px 2px 4px rgba(0,0,0,0.5);">
        Live Preview
    </h2>
    <p style="color: white;">Background color updates in real-time as you select</p>
</div>

@code {
    private string bgColor = "rgba(52, 152, 219, 0.9)";
    
    private void OnBackgroundChange(ColorPickerEventArgs args)
    {
        bgColor = args.CurrentValue.Rgba;
        StateHasChanged();
    }
}

Multi-Element Theme Preview

@page "/theme-preview"
@using Syncfusion.Blazor.Inputs

<div class="theme-builder">
    <div class="controls">
        <div>
            <label>Primary:</label>
            <SfColorPicker @bind-Value="@primaryColor"></SfColorPicker>
        </div>
        <div>
            <label>Secondary:</label>
            <SfColorPicker @bind-Value="@secondaryColor"></SfColorPicker>
        </div>
        <div>
            <label>Accent:</label>
            <SfColorPicker @bind-Value="@accentColor"></SfColorPicker>
        </div>
    </div>
    
    <div class="preview">
        <button style="background-color: @primaryColor; color: white; border: none; padding: 10px 20px; border-radius: 4px;">
            Primary Button
        </button>
        <button style="background-color: @secondaryColor; color: white; border: none; padding: 10px 20px; border-radius: 4px;">
            Secondary Button
        </button>
        <button style="background-color: @accentColor; color: white; border: none; padding: 10px 20px; border-radius: 4px;">
            Accent Button
        </button>
    </div>
</div>

@code {
    private string primaryColor = "#3498db";
    private string secondaryColor = "#2ecc71";
    private string accentColor = "#e74c3c";
}

Debounced Updates for Performance

<SfColorPicker @bind-Value="@color" 
               ValueChange="@OnColorChangeDebounced">
</SfColorPicker>

<p>Updates: @updateCount (debounced)</p>

@code {
    private string color = "#9b59b6";
    private int updateCount = 0;
    private System.Threading.Timer debounceTimer;
    
    private void OnColorChangeDebounced(ColorPickerEventArgs args)
    {
        debounceTimer?.Dispose();
        
        debounceTimer = new System.Threading.Timer(_ =>
        {
            InvokeAsync(() =>
            {
                updateCount++;
                // Perform expensive operation here
                Console.WriteLine($"Debounced update: {args.CurrentValue.Hex}");
                StateHasChanged();
            });
        }, null, 300, System.Threading.Timeout.Infinite);
    }
    
    public void Dispose()
    {
        debounceTimer?.Dispose();
    }
}

Best Practices

1. Use appropriate events: ValueChanged for real-time, Selected for confirmation 2. Async handlers: Use async/await for I/O operations 3. Debouncing: Debounce frequent updates for performance 4. Validation: Validate colors in event handlers 5. Preview: Show real-time preview of color changes 6. Error handling: Handle event errors gracefully 7. State management: Call StateHasChanged() when needed 8. Cleanup: Dispose timers and resources 9. User feedback: Show loading states during async operations 10. Accessibility: Announce color changes to screen readers

Related Topics

• Getting Started: Basic setup → colorpicker-getting-started.md
• Modes: Configuration options → colorpicker-modes-configuration.md
• Customization: Styling and accessibility → colorpicker-customization-accessibility.md

ColorPicker - Getting Started

This guide covers the installation, basic setup, and initial configuration of the Syncfusion Blazor ColorPicker component.

Installation

NuGet Package

Install the Syncfusion.Blazor.Inputs package:

Package Manager Console:

Install-Package Syncfusion.Blazor.Inputs

NuGet Package Manager UI: 1. Right-click on project → Manage NuGet Packages 2. Search for "Syncfusion.Blazor.Inputs" 3. Install the latest version

.NET CLI:

dotnet add package Syncfusion.Blazor.Inputs

Service Registration

Register Syncfusion Blazor services in your application:

Program.cs (.NET 6+):

using Syncfusion.Blazor;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSyncfusionBlazor();
// ... other services

var app = builder.Build();
// ... middleware configuration
app.Run();

Startup.cs (.NET 5 and earlier):

public void ConfigureServices(IServiceCollection services)
{
    services.AddSyncfusionBlazor();
}

CSS Theme Configuration

Add Syncfusion theme CSS to your application:

wwwroot/index.html (Blazor WebAssembly) or _Host.cshtml / _Layout.cshtml (Blazor Server):

<head>
    <!-- Material theme -->
    <link href="_content/Syncfusion.Blazor.Themes/material.css" rel="stylesheet" />
    
    <!-- Or choose another theme: -->
    <!-- <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" /> -->
    <!-- <link href="_content/Syncfusion.Blazor.Themes/fluent.css" rel="stylesheet" /> -->
    <!-- <link href="_content/Syncfusion.Blazor.Themes/tailwind.css" rel="stylesheet" /> -->
</head>

Namespace Import

Add the namespace in your component or _Imports.razor:

_Imports.razor:

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Inputs

Basic ColorPicker Setup

Minimal Example

@using Syncfusion.Blazor.Inputs

<SfColorPicker @bind-Value="@color"></SfColorPicker>

@code {
    private string color = "#008000";
}

This creates a basic color picker with the default Picker mode (gradient selector).

With Label and Preview

@using Syncfusion.Blazor.Inputs

<div class="colorpicker-container">
    <label for="myColorPicker">Select Color:</label>
    <SfColorPicker @bind-Value="@selectedColor" 
                   ID="myColorPicker">
    </SfColorPicker>
    
    <div class="preview" style="background-color: @selectedColor; width: 100px; height: 50px; margin-top: 10px;">
        <p style="color: white; padding: 10px;">@selectedColor</p>
    </div>
</div>

@code {
    private string selectedColor = "#3498db";
}

Value Binding

The ColorPicker value can be bound in multiple formats:

Hex Format (Most Common)

<SfColorPicker @bind-Value="@hexColor"></SfColorPicker>

@code {
    private string hexColor = "#FF5733"; // Hex format
}

RGBA Format (with opacity)

<SfColorPicker @bind-Value="@rgbaColor" 
               EnableOpacity="true">
</SfColorPicker>

@code {
    private string rgbaColor = "rgba(255, 87, 51, 0.5)"; // RGBA format
}

HSVA Format

<SfColorPicker @bind-Value="@hsvaColor">
</SfColorPicker>

@code {
    private string hsvaColor = "hsva(9, 80%, 100%, 1)"; // HSVA format
}

Mode Overview

The ColorPicker supports two selection modes:

Picker Mode (Default - Gradient Selector)

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Picker">
</SfColorPicker>

@code {
    private string color = "#008000";
}

Features:

• Full color spectrum gradient
• Hue, saturation, value controls
• Allows selection of any color
• Best for design tools and unrestricted selection

Palette Mode (Predefined Colors Grid)

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Palette">
</SfColorPicker>

@code {
    private string color = "#008000";
}

Features:

• Grid of predefined colors
• Quick selection from preset palette
• Configurable columns and color sets
• Best for limited color choices (brand colors, theme colors)

Complete Getting Started Example

@page "/colorpicker-demo"
@using Syncfusion.Blazor.Inputs

<h3>ColorPicker Getting Started</h3>

<div class="example-section">
    <h4>1. Basic Picker Mode</h4>
    <SfColorPicker @bind-Value="@pickerColor" 
                   Mode="ColorPickerMode.Picker">
    </SfColorPicker>
    <p>Selected: @pickerColor</p>
</div>

<div class="example-section">
    <h4>2. Palette Mode</h4>
    <SfColorPicker @bind-Value="@paletteColor" 
                   Mode="ColorPickerMode.Palette">
    </SfColorPicker>
    <p>Selected: @paletteColor</p>
</div>

<div class="example-section">
    <h4>3. With Opacity</h4>
    <SfColorPicker @bind-Value="@opacityColor" 
                   EnableOpacity="true">
    </SfColorPicker>
    <p>Selected: @opacityColor</p>
    <div style="background-color: @opacityColor; width: 200px; height: 50px; border: 1px solid #ccc;">
        Preview with opacity
    </div>
</div>

@code {
    private string pickerColor = "#e74c3c";
    private string paletteColor = "#3498db";
    private string opacityColor = "rgba(46, 204, 113, 0.5)";
}

<style>
    .example-section {
        margin-bottom: 30px;
        padding: 20px;
        border: 1px solid #ddd;
        border-radius: 5px;
    }
</style>

Initial Value Configuration

Setting Initial Color

<SfColorPicker @bind-Value="@brandColor"></SfColorPicker>

@code {
    private string brandColor = "#e74c3c"; // Set initial value
    
    protected override void OnInitialized()
    {
        // Can also set dynamically on initialization
        brandColor = GetBrandColorFromSettings();
    }
    
    private string GetBrandColorFromSettings()
    {
        // Retrieve from settings, database, etc.
        return "#3498db";
    }
}

Default Value from User Preferences

<SfColorPicker @bind-Value="@userThemeColor"></SfColorPicker>

@code {
    private string userThemeColor;
    
    protected override async Task OnInitializedAsync()
    {
        // Load from user preferences
        userThemeColor = await LoadUserPreferenceAsync("themeColor") ?? "#008000";
    }
    
    private async Task<string> LoadUserPreferenceAsync(string key)
    {
        // Simulate loading from local storage or API
        return "#9b59b6";
    }
}

Next Steps

• Modes & Configuration: Learn about Picker vs Palette modes, inline display, and mode switching → colorpicker-modes-configuration.md
• Preset Colors: Configure custom color palettes and recent colors → colorpicker-presets-colors.md
• Opacity: Enable alpha channel for transparency → colorpicker-opacity-values.md
• Events: Handle value changes and user interactions → colorpicker-events-binding.md
• Customization: Styling, accessibility, and advanced customization → colorpicker-customization-accessibility.md

ColorPicker - Modes and Configuration

Table of Contents

• Overview
• Picker Mode
• Palette Mode
• Inline vs Popup Display
• Mode Switcher
• Columns Configuration
• Show Buttons
• Mode Selection Guide

Overview

The Syncfusion Blazor ColorPicker offers two distinct selection modes, each optimized for different use cases:

1. Picker Mode (default): Full gradient-based color selector with unlimited color choices 2. Palette Mode: Grid-based selection from predefined color sets

You can configure the display behavior (popup vs inline) and allow users to switch between modes dynamically.

Picker Mode

Picker mode provides a gradient-based color selector that allows users to choose any color from the full spectrum.

Basic Picker Mode

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Picker">
</SfColorPicker>

@code {
    private string color = "#008000";
}

Features of Picker Mode

• Gradient Area: Large color spectrum for precise selection
• Hue Bar: Vertical or horizontal bar for hue selection
• Preview: Shows current and previous color
• Hex Input: Manual hex value entry
• Opacity Control: Optional alpha slider (with EnableOpacity="true")

Picker Mode with Opacity

<SfColorPicker @bind-Value="@colorWithOpacity" 
               Mode="ColorPickerMode.Picker"
               EnableOpacity="true">
</SfColorPicker>

@code {
    private string colorWithOpacity = "rgba(231, 76, 60, 0.7)";
}

When to Use Picker Mode

• Design tools: Graphic editors, drawing applications, image annotation
• Unrestricted selection: When users need any color from the spectrum
• Professional applications: CAD, design software, development tools
• Custom styling: User-defined themes, personalization features
• Precise color matching: When exact color values are critical

Palette Mode

Palette mode displays a grid of predefined colors for quick selection.

Basic Palette Mode

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Palette">
</SfColorPicker>

@code {
    private string color = "#e74c3c";
}

Default Palette

The default palette includes:

• Material design colors
• Standard web colors
• Recent colors (if enabled)

Palette with Custom Columns

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Palette"
               Columns="8">
</SfColorPicker>

@code {
    private string color = "#3498db";
}

When to Use Palette Mode

• Brand colors: Limit selection to company/brand color palette
• Themed applications: Predefined theme color choices
• Simplified UX: Reduce decision fatigue with curated colors
• Consistency: Ensure color consistency across application
• Quick selection: Fast color picking without exploration

Inline vs Popup Display

Control whether the ColorPicker appears inline (always visible) or as a popup (triggered by button click).

Popup Display (Default)

<SfColorPicker @bind-Value="@color" 
               Inline="false">
</SfColorPicker>

@code {
    private string color = "#008000";
}

Behavior:

• Shows a color preview button
• Clicking button opens color picker popup
• User selects color in popup
• Can show Apply/Cancel buttons with ShowButtons="true"

Inline Display

<SfColorPicker @bind-Value="@color" 
               Inline="true">
</SfColorPicker>

@code {
    private string color = "#008000";
}

Behavior:

• ColorPicker always visible
• No popup or button trigger
• Immediate selection feedback
• Takes up more screen space

When to Use Inline Display

@page "/theme-builder"
@using Syncfusion.Blazor.Inputs

<div class="theme-panel">
    <h3>Theme Customization</h3>
    
    <div class="color-option">
        <label>Primary Color:</label>
        <SfColorPicker @bind-Value="@primaryColor" 
                       Inline="true"
                       Mode="ColorPickerMode.Palette">
        </SfColorPicker>
    </div>
    
    <div class="color-option">
        <label>Accent Color:</label>
        <SfColorPicker @bind-Value="@accentColor" 
                       Inline="true"
                       Mode="ColorPickerMode.Palette">
        </SfColorPicker>
    </div>
</div>

@code {
    private string primaryColor = "#3498db";
    private string accentColor = "#e74c3c";
}

<style>
    .theme-panel {
        padding: 20px;
        border: 1px solid #ddd;
    }
    
    .color-option {
        margin-bottom: 20px;
    }
</style>

Best for:

• Settings panels
• Theme builders
• Design tools
• Color customization screens
• When space is not a constraint

Mode Switcher

Allow users to toggle between Picker and Palette modes dynamically.

Enable Mode Switcher

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Picker"
               ModeSwitcher="true">
</SfColorPicker>

@code {
    private string color = "#9b59b6";
}

Features:

• Shows mode toggle icon in UI
• Users can switch between Picker and Palette
• Current selection preserved when switching
• Fires ModeSwitched event on mode change

Mode Switcher with Event Handling

<SfColorPicker @bind-Value="@color" 
               Mode="@currentMode"
               ModeSwitcher="true"
               ModeSwitched="@OnModeChanged">
</SfColorPicker>

<p>Current Mode: @currentMode</p>

@code {
    private string color = "#2ecc71";
    private ColorPickerMode currentMode = ColorPickerMode.Picker;
    
    private void OnModeChanged(ModeSwitchEventArgs args)
    {
        currentMode = args.Mode;
        Console.WriteLine($"Mode changed to: {currentMode}");
    }
}

When to Enable Mode Switcher

• Flexible workflows: Users may prefer different modes for different tasks
• Learning applications: Help users understand both selection methods
• Power users: Give advanced users choice of tool
• Hybrid use cases: Some colors need precise picking, others quick selection

Columns Configuration

Control the number of columns in Palette mode for optimal layout.

Default Columns (10)

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Palette">
</SfColorPicker>

Custom Column Count

<SfColorPicker @bind-Value="@color" 
               Mode="ColorPickerMode.Palette"
               Columns="5">
</SfColorPicker>

@code {
    private string color = "#f39c12";
}

Responsive Column Layout

<div class="desktop-view">
    <SfColorPicker @bind-Value="@colorDesktop" 
                   Mode="ColorPickerMode.Palette"
                   Columns="10">
    </SfColorPicker>
</div>

<div class="mobile-view">
    <SfColorPicker @bind-Value="@colorMobile" 
                   Mode="ColorPickerMode.Palette"
                   Columns="5">
    </SfColorPicker>
</div>

@code {
    private string colorDesktop = "#1abc9c";
    private string colorMobile = "#1abc9c";
}

Column Count Recommendations

Show Buttons

Display Apply and Cancel buttons for popup mode (requires user confirmation).

Without Buttons (Default)

<SfColorPicker @bind-Value="@color" 
               ShowButtons="false">
</SfColorPicker>

@code {
    private string color = "#e67e22";
}

Behavior:

• Color changes immediately on selection
• Popup closes automatically
• No confirmation required

With Apply/Cancel Buttons

<SfColorPicker @bind-Value="@color" 
               ShowButtons="true">
</SfColorPicker>

@code {
    private string color = "#16a085";
}

Behavior:

• Color changes only when Apply clicked
• Cancel reverts to previous color
• User must confirm selection
• Popup remains open until Apply/Cancel

Buttons with Event Handling

<SfColorPicker @bind-Value="@color" 
               ShowButtons="true"
               ValueChange="@OnColorApplied">
</SfColorPicker>

<p>Applied Color: @color</p>

@code {
    private string color = "#c0392b";
    
    private void OnColorApplied(ColorPickerEventArgs args)
    {
        Console.WriteLine($"Color applied: {args.CurrentValue.Hex}");
        // Save to database, update UI, etc.
    }
}

When to Use Buttons

Enable buttons when:

• Changes have significant impact (theme changes, expensive operations)
• User needs preview before committing
• Undo/cancel is important
• Batch operations are involved
• Professional/enterprise applications

Disable buttons when:

• Immediate feedback is desired
• Lightweight, exploratory color selection
• Real-time preview is the primary use case
• Mobile/touch-first interfaces
• Simplified user experience preferred

Mode Selection Guide

Decision Matrix

Example: Complete Configuration

@page "/colorpicker-advanced"
@using Syncfusion.Blazor.Inputs

<h3>Advanced ColorPicker Configuration</h3>

<div class="example">
    <h4>Design Tool Mode (Flexible)</h4>
    <SfColorPicker @bind-Value="@designColor" 
                   Mode="ColorPickerMode.Picker"
                   ModeSwitcher="true"
                   EnableOpacity="true"
                   ShowButtons="true">
    </SfColorPicker>
    <p>Selected: @designColor</p>
</div>

<div class="example">
    <h4>Brand Palette (Restricted)</h4>
    <SfColorPicker @bind-Value="@brandColor" 
                   Mode="ColorPickerMode.Palette"
                   Columns="6"
                   ShowButtons="false"
                   Inline="true">
    </SfColorPicker>
    <p>Selected: @brandColor</p>
</div>

<div class="example">
    <h4>Quick Popup Selector</h4>
    <SfColorPicker @bind-Value="@quickColor" 
                   Mode="ColorPickerMode.Palette"
                   ShowButtons="false">
    </SfColorPicker>
    <p>Selected: @quickColor</p>
</div>

@code {
    private string designColor = "rgba(52, 152, 219, 0.8)";
    private string brandColor = "#e74c3c";
    private string quickColor = "#2ecc71";
}

Best Practices

1. Choose the right mode: Use Picker for unrestricted selection, Palette for curated choices 2. Enable ModeSwitcher: For power users who want flexibility 3. Configure columns wisely: Match screen size and available space 4. Use buttons for significant changes: When color change has major impact 5. Inline for settings: Use inline display in dedicated customization panels 6. Popup for forms: Use popup mode for general form inputs 7. Test on devices: Ensure column count works on target devices 8. Provide feedback: Show color preview to confirm user selection

Related Topics

• Preset Colors: Custom color palettes → colorpicker-presets-colors.md
• Opacity: Alpha channel configuration → colorpicker-opacity-values.md
• Events: Handle mode switching and selection → colorpicker-events-binding.md

File Upload Configuration

Table of Contents

• ID Property
• AllowedExtensions
• AllowMultiple
• AutoUpload
• SequentialUpload
• DirectoryUpload
• MaxFileSize
• MinFileSize
• Enabled State
• Name Property
• Configuration Examples

---

ID Property

The ID property provides a unique identifier for the FileUpload component. This is essential for referencing the component in JavaScript, CSS, and server-side operations.

<SfUploader ID="myFileUploadComponent" name="UploadFiles" />

When to use:

• Referencing component in JavaScript interop
• Styling specific upload instances
• Server-side parameter matching (name attribute)

Note: The ID value must be unique across your application. When using AsyncSettings, the name property must match the controller's POST method parameter name.

---

AllowedExtensions

The AllowedExtensions property specifies which file types can be uploaded. This provides client-side validation and file type filtering.

<SfUploader AllowedExtensions=".jpg,.jpeg,.png,.gif" />

Common Extension Sets

Images:

AllowedExtensions=".jpg,.jpeg,.png,.gif,.bmp,.svg"

Documents:

AllowedExtensions=".pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx"

Media:

AllowedExtensions=".mp4,.mov,.avi,.mp3,.wav,.flac"

Multiple Types:

AllowedExtensions=".pdf,.jpg,.png,.docx"

Important Notes:

• Multiple extensions separated by commas
• Include the leading dot (.jpg not jpg)
• Matching is case-insensitive
• Always perform server-side validation for security

---

AllowMultiple

The AllowMultiple property determines whether users can select one or multiple files at once.

<!-- Single file only -->
<SfUploader AllowMultiple="false" />

<!-- Multiple files allowed -->
<SfUploader AllowMultiple="true" />

Use Cases

Default: true (multiple file selection enabled)

---

AutoUpload

The AutoUpload property controls whether files upload immediately after selection or wait for manual upload button click.

<!-- Automatic upload -->
<SfUploader AutoUpload="true" />

<!-- Manual upload button required -->
<SfUploader AutoUpload="false" />

Comparison

Default: true

Example with Manual Upload:

<SfUploader @ref="uploader" AutoUpload="false">
    <UploaderAsyncSettings SaveUrl="api/upload/save"></UploaderAsyncSettings>
</SfUploader>

<button @onclick="UploadFiles">Upload Selected Files</button>

@code {
    SfUploader uploader;
    
    private async Task UploadFiles()
    {
        // Trigger upload manually
        await uploader.UploadAsync();
    }
}

---

SequentialUpload

The SequentialUpload property (only active when AllowMultiple="true") determines upload order for multiple files.

<!-- Upload all files concurrently -->
<SfUploader AllowMultiple="true" SequentialUpload="false" />

<!-- Upload files one at a time -->
<SfUploader AllowMultiple="true" SequentialUpload="true" />

Comparison

Default: false

Note: Useful for managing server load and ensuring orderly processing of uploaded files.

---

DirectoryUpload

The DirectoryUpload property enables users to select and upload entire directories instead of individual files.

<SfUploader DirectoryUpload="true" />

Features

• Select entire folder structure
• Maintains folder hierarchy
• Useful for bulk uploads
• Browser support varies

Default: false

Use Cases:

• Backup folder uploads
• Project folder uploads
• Archive extraction preparation

---

MaxFileSize

The MaxFileSize property sets the maximum allowed file size in bytes. Prevents users from uploading files exceeding this limit.

<!-- 10 MB limit -->
<SfUploader MaxFileSize="10485760" />

<!-- 100 MB limit -->
<SfUploader MaxFileSize="104857600" />

<!-- 1 GB limit -->
<SfUploader MaxFileSize="1073741824" />

Size Conversion Reference

• 1 KB = 1,024 bytes
• 1 MB = 1,048,576 bytes (1024 × 1024)
• 10 MB = 10,485,760 bytes
• 100 MB = 104,857,600 bytes
• 1 GB = 1,073,741,824 bytes

Important:

• Server infrastructure (Kestrel/IIS) imposes additional limits
• Align client limits with server configuration

Server Configuration Example (ASP.NET Core):

// Program.cs
builder.Services.Configure<FormOptions>(options =>
{
    options.MultipartBodyLengthLimit = 104857600; // 100 MB
});

---

MinFileSize

The MinFileSize property sets the minimum required file size in bytes. Prevents uploading empty or very small files.

<!-- Minimum 1 KB -->
<SfUploader MinFileSize="1024" />

<!-- Minimum 5 MB -->
<SfUploader MinFileSize="5242880" />

Common Scenarios

• Avoid empty file uploads: MinFileSize="1"
• Ensure meaningful data: MinFileSize="1024" (1 KB)

Default: 0 bytes (no minimum)

---

Enabled State

The Enabled property controls whether the FileUpload component is interactive or disabled.

<!-- Component is active -->
<SfUploader Enabled="true" />

<!-- Component is disabled -->
<SfUploader Enabled="false" />

Dynamic Enable/Disable

<SfUploader @ref="uploader" Enabled="@isEnabled" />

<button @onclick="@(() => isEnabled = !isEnabled)">Toggle Upload</button>

@code {
    SfUploader uploader;
    bool isEnabled = true;
}

Use Cases:

• Disable until form validation passes
• Disable during payment processing
• Disable based on user permissions

---

Name Property

The name attribute in the HTML input element must match the server-side POST method parameter name.

<!-- Component name must match controller parameter -->
<SfUploader name="UploadFiles" />

Server-Side Match:

[HttpPost("[action]")]
public void Save(IList<IFormFile> UploadFiles)
{
    // 'UploadFiles' must match name attribute above
    foreach (var file in UploadFiles)
    {
        // Process file
    }
}

Note: If ID differs from desired name, use htmlAttributes property:

<SfUploader ID="fileUploadId" name="DocumentFiles" />

---

Configuration Examples

Example 1: Strict Image Upload

<SfUploader 
    AutoUpload="true"
    AllowMultiple="false"
    AllowedExtensions=".jpg,.jpeg,.png"
    MaxFileSize="5242880"
    ID="profilePictureUpload"
    name="ProfilePicture">
    <UploaderAsyncSettings SaveUrl="api/profile/upload"></UploaderAsyncSettings>
</SfUploader>

Example 2: Batch Document Upload

<SfUploader 
    AutoUpload="false"
    AllowMultiple="true"
    SequentialUpload="true"
    AllowedExtensions=".pdf,.doc,.docx"
    MaxFileSize="52428800"
    MinFileSize="1024"
    ID="documentBatchUpload"
    name="Documents">
    <UploaderAsyncSettings SaveUrl="api/documents/save"></UploaderAsyncSettings>
</SfUploader>

Example 3: Flexible File Upload with Directory Support

<SfUploader 
    AutoUpload="false"
    AllowMultiple="true"
    DirectoryUpload="true"
    AllowedExtensions=".jpg,.pdf,.docx,.xlsx"
    MaxFileSize="104857600"
    ID="flexibleUpload"
    name="FlexibleFiles">
    <UploaderAsyncSettings SaveUrl="api/files/save"></UploaderAsyncSettings>
</SfUploader>

Example 4: Progressive Upload Control

<SfUploader 
    @ref="uploader"
    AutoUpload="false"
    AllowMultiple="true"
    Enabled="@uploadEnabled"
    AllowedExtensions=".jpg,.png,.pdf"
    MaxFileSize="10485760">
    <UploaderAsyncSettings SaveUrl="api/upload/save"></UploaderAsyncSettings>
</SfUploader>

<button @onclick="@(() => uploadEnabled = !uploadEnabled)">
    Toggle Upload: @(uploadEnabled ? "Enabled" : "Disabled")
</button>

@code {
    SfUploader uploader;
    bool uploadEnabled = true;
}

---

Key Configuration Checklist

Before deploying file upload feature, verify:

• ✓ AllowedExtensions matches security policy
• ✓ MaxFileSize aligns with server limits
• ✓ name attribute matches server parameter
• ✓ AutoUpload matches user workflow
• ✓ AllowMultiple matches use case
• ✓ Server-side validation implemented
• ✓ Upload directory has write permissions
• ✓ API endpoint properly secured