---
title: 'Loading'
description: 'Loading indicators and overlays for async operations'
---

## Overview

Hux UI provides loading components for indicating async operations:

- **HuxLoading** - Customizable loading indicators
- **HuxLoadingOverlay** - Full-screen loading overlays

![HuxLoading Indicators](/images/hux-loading.png)

## Component Variants

### Small Loading Indicator
Compact loading indicator for tight spaces:
```dart
HuxLoading(size: HuxLoadingSize.small)
```

### Medium Loading Indicator
Standard loading indicator (default size):
```dart
HuxLoading(size: HuxLoadingSize.medium)
```

### Large Loading Indicator
Prominent loading indicator for important operations:
```dart
HuxLoading(size: HuxLoadingSize.large)
```

### Extra Large Loading Indicator
Maximum size loading indicator:
```dart
HuxLoading(size: HuxLoadingSize.extraLarge)
```

### Loading with Custom Colors
Loading indicator with theme-aware colors:
```dart
HuxLoading(
  size: HuxLoadingSize.medium,
  color: HuxTokens.primary(context),
)
```

## HuxLoading

### Sizes

- `small` - Compact loading indicator
- `medium` - Standard loading indicator (default)
- `large` - Prominent loading indicator

## HuxLoadingOverlay

Full-screen overlay that blocks user interaction during loading operations. Perfect for API calls, file uploads, or any long-running processes.

```dart
HuxLoadingOverlay(
  isLoading: _isLoading,
  message: 'Processing...',
  child: YourContent(),
)
```

### Properties

- **`isLoading`** - Boolean flag to control overlay visibility
- **`message`** - Optional loading message displayed above the spinner
- **`child`** - The main content widget that will be covered by the overlay
- **`barrierColor`** - Optional custom barrier color (defaults to semi-transparent black)
- **`spinnerColor`** - Optional custom spinner color (defaults to theme primary color)

### Advanced Usage

```dart
HuxLoadingOverlay(
  isLoading: _isLoading,
  message: 'Uploading files...',
  barrierColor: Colors.black54,
  spinnerColor: HuxTokens.primary(context),
  child: Scaffold(
    appBar: AppBar(title: Text('File Upload')),
    body: FileUploadForm(),
  ),
)
```

## Usage Example

```dart
class AsyncOperationExample extends StatefulWidget {
  @override
  _AsyncOperationExampleState createState() => _AsyncOperationExampleState();
}

class _AsyncOperationExampleState extends State<AsyncOperationExample> {
  bool _isLoading = false;

  void _performAsyncOperation() async {
    setState(() {
      _isLoading = true;
    });

    // Simulate async work
    await Future.delayed(Duration(seconds: 3));

    setState(() {
      _isLoading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return HuxLoadingOverlay(
      isLoading: _isLoading,
      message: 'Loading data...',
      child: Column(
        children: [
          HuxButton(
            onPressed: _isLoading ? null : _performAsyncOperation,
            isLoading: _isLoading,
            child: Text('Start Operation'),
          ),
        ],
      ),
    );
  }
}
```

## Best Practices

1. **Use for blocking operations** - Perfect for API calls, file uploads, or data processing
2. **Provide clear messages** - Help users understand what's happening
3. **Consider duration** - For very short operations (< 500ms), consider using inline loading instead
4. **Accessibility** - The overlay automatically handles screen reader announcements
5. **Theme integration** - Colors automatically adapt to light/dark themes

## Accessibility Features

- **Screen reader support** - Loading state is announced to assistive technologies
- **Focus management** - Prevents interaction with background content during loading
- **High contrast support** - Uses Hux UI's accessible color tokens
- **Keyboard navigation** - Properly blocks keyboard input during loading states
