gluestack-accessibility

What this skill does

# gluestack-ui - Accessibility

Expert knowledge of building accessible user interfaces with gluestack-ui, ensuring WCAG 2.1 AA compliance across React and React Native platforms.

## Overview

gluestack-ui components are built with accessibility in mind, following WAI-ARIA guidelines and providing built-in support for screen readers, keyboard navigation, and focus management. This skill covers best practices for maintaining and enhancing accessibility.

## Key Concepts

### Built-in Accessibility

gluestack-ui components include accessibility features out of the box:

```tsx
// Button automatically has role="button" and handles focus
<Button onPress={handlePress}>
  <ButtonText>Submit</ButtonText>
</Button>

// Modal manages focus trap and escape key handling
<Modal isOpen={isOpen} onClose={onClose}>
  <ModalContent>
    <ModalBody>Content</ModalBody>
  </ModalContent>
</Modal>

// Form controls link labels to inputs
<FormControl>
  <FormControlLabel>
    <FormControlLabelText>Email</FormControlLabelText>
  </FormControlLabel>
  <Input>
    <InputField />
  </Input>
</FormControl>
```

### Accessibility Props

React Native accessibility props supported by gluestack-ui:

```tsx
<Pressable
  accessibilityLabel="Close dialog"
  accessibilityHint="Closes the current dialog and returns to the previous screen"
  accessibilityRole="button"
  accessibilityState={{ disabled: isDisabled }}
  accessible={true}
  onPress={onClose}
>
  <Icon as={CloseIcon} />
</Pressable>
```

### ARIA Attributes for Web

For web platforms, use ARIA attributes:

```tsx
import { Platform } from 'react-native';

<Button
  {...(Platform.OS === 'web' && {
    'aria-label': 'Close dialog',
    'aria-describedby': 'dialog-description',
    'aria-expanded': isExpanded,
  })}
  onPress={handlePress}
>
  <ButtonText>Toggle</ButtonText>
</Button>
```

## Screen Reader Support

### Meaningful Labels

Provide descriptive labels for interactive elements:

```tsx
// Bad: No context for screen reader users
<Button onPress={handleDelete}>
  <ButtonIcon as={TrashIcon} />
</Button>

// Good: Clear accessibility label
<Button
  onPress={handleDelete}
  accessibilityLabel="Delete item"
  accessibilityHint="Permanently removes this item from your list"
>
  <ButtonIcon as={TrashIcon} />
</Button>
```

### Announcing Dynamic Changes

Use accessibility live regions for dynamic content:

```tsx
import { AccessibilityInfo } from 'react-native';

function SearchResults({ results, isLoading }: {
  results: Item[];
  isLoading: boolean;
}) {
  useEffect(() => {
    if (!isLoading) {
      AccessibilityInfo.announceForAccessibility(
        `${results.length} results found`
      );
    }
  }, [results, isLoading]);

  return (
    <VStack
      accessibilityRole="list"
      accessibilityLabel={`Search results, ${results.length} items`}
    >
      {results.map((item) => (
        <Box key={item.id} accessibilityRole="listitem">
          <Text>{item.name}</Text>
        </Box>
      ))}
    </VStack>
  );
}
```

### Image Accessibility

Always provide alt text for images:

```tsx
import { Image } from '@/components/ui/image';

// Informative image
<Image
  source={{ uri: product.imageUrl }}
  alt={`${product.name} - ${product.color} color option`}
  className="w-full h-48 rounded-lg"
/>

// Decorative image (hide from screen readers)
<Image
  source={require('@/assets/decorative-pattern.png')}
  alt=""
  accessibilityElementsHidden={true}
  importantForAccessibility="no-hide-descendants"
  className="absolute inset-0 opacity-10"
/>
```

## Keyboard Navigation

### Focus Management

Ensure proper focus order and visibility:

```tsx
import { useRef, useEffect } from 'react';
import { TextInput } from 'react-native';

function SearchModal({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
  const searchInputRef = useRef<TextInput>(null);

  useEffect(() => {
    if (isOpen) {
      // Focus the search input when modal opens
      searchInputRef.current?.focus();
    }
  }, [isOpen]);

  return (
    <Modal isOpen={isOpen} onClose={onClose}>
      <ModalContent>
        <ModalHeader>
          <Heading>Search</Heading>
          <ModalCloseButton />
        </ModalHeader>
        <ModalBody>
          <Input>
            <InputField
              ref={searchInputRef}
              placeholder="Search..."
              accessibilityLabel="Search input"
            />
          </Input>
        </ModalBody>
      </ModalContent>
    </Modal>
  );
}
```

### Focus Trap in Modals

gluestack-ui Modal automatically traps focus, but you can enhance it:

```tsx
function AccessibleModal({ isOpen, onClose, children }: {
  isOpen: boolean;
  onClose: () => void;
  children: React.ReactNode;
}) {
  return (
    <Modal
      isOpen={isOpen}
      onClose={onClose}
      closeOnOverlayClick={true}
      // Escape key closes modal (built-in)
    >
      <ModalBackdrop />
      <ModalContent
        accessibilityRole="dialog"
        accessibilityModal={true}
        accessibilityLabel="Dialog"
      >
        {children}
      </ModalContent>
    </Modal>
  );
}
```

### Keyboard Shortcuts

Implement keyboard shortcuts for web:

```tsx
import { useEffect } from 'react';
import { Platform } from 'react-native';

function useKeyboardShortcut(key: string, callback: () => void) {
  useEffect(() => {
    if (Platform.OS !== 'web') return;

    const handleKeyDown = (event: KeyboardEvent) => {
      if (event.key === key && (event.metaKey || event.ctrlKey)) {
        event.preventDefault();
        callback();
      }
    };

    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);
  }, [key, callback]);
}

// Usage
function SearchBar() {
  const inputRef = useRef<TextInput>(null);

  useKeyboardShortcut('k', () => {
    inputRef.current?.focus();
  });

  return (
    <Input>
      <InputField
        ref={inputRef}
        placeholder="Search (Cmd+K)"
        accessibilityKeyShortcuts={['cmd+k']}
      />
    </Input>
  );
}
```

## Form Accessibility

### Label Association

Properly associate labels with form controls:

```tsx
import {
  FormControl,
  FormControlLabel,
  FormControlLabelText,
  FormControlHelper,
  FormControlHelperText,
  FormControlError,
  FormControlErrorIcon,
  FormControlErrorText,
} from '@/components/ui/form-control';
import { Input, InputField } from '@/components/ui/input';
import { AlertCircleIcon } from 'lucide-react-native';

function AccessibleFormField({
  label,
  placeholder,
  helperText,
  error,
  isRequired,
  value,
  onChange,
}: {
  label: string;
  placeholder: string;
  helperText?: string;
  error?: string;
  isRequired?: boolean;
  value: string;
  onChange: (text: string) => void;
}) {
  return (
    <FormControl isRequired={isRequired} isInvalid={!!error}>
      <FormControlLabel>
        <FormControlLabelText>{label}</FormControlLabelText>
      </FormControlLabel>
      <Input>
        <InputField
          placeholder={placeholder}
          value={value}
          onChangeText={onChange}
          accessibilityLabel={label}
          accessibilityHint={helperText}
        />
      </Input>
      {error ? (
        <FormControlError>
          <FormControlErrorIcon as={AlertCircleIcon} />
          <FormControlErrorText>{error}</FormControlErrorText>
        </FormControlError>
      ) : helperText ? (
        <FormControlHelper>
          <FormControlHelperText>{helperText}</FormControlHelperText>
        </FormControlHelper>
      ) : null}
    </FormControl>
  );
}
```

### Error Announcement

Announce form errors to screen readers:

```tsx
import { AccessibilityInfo } from 'react-native';

function FormWithValidation() {
  const [errors, setErrors] = useState<Record<string, string>>({});

  const validateAndSubmit = () => {
    const newErrors: Record<string, string> = {};

    if (!formData.email) {
      newErrors.email = 'Email is required';
    }
    if (!formData.password) {
      newE