> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thehuxdesign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Loading

> 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

<img src="https://mintcdn.com/thehuxdesign/C1mIYJAVASUv1pZO/images/hux-loading.png?fit=max&auto=format&n=C1mIYJAVASUv1pZO&q=85&s=2a678e18847dfd2403cac4fbe967a39a" alt="HuxLoading Indicators" width="1528" height="232" data-path="images/hux-loading.png" />

## Component Variants

### Small Loading Indicator

Compact loading indicator for tight spaces:

```dart theme={null}
HuxLoading(size: HuxLoadingSize.small)
```

### Medium Loading Indicator

Standard loading indicator (default size):

```dart theme={null}
HuxLoading(size: HuxLoadingSize.medium)
```

### Large Loading Indicator

Prominent loading indicator for important operations:

```dart theme={null}
HuxLoading(size: HuxLoadingSize.large)
```

### Extra Large Loading Indicator

Maximum size loading indicator:

```dart theme={null}
HuxLoading(size: HuxLoadingSize.extraLarge)
```

### Loading with Custom Colors

Loading indicator with theme-aware colors:

```dart theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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