Accessibility in Nuxt: What It Is, How It Works, and How to Optimize

<!-- app.vue -->
<template>
  <NuxtRouteAnnouncer />
  <NuxtPage />
</template>

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      titleTemplate: '%s | My Site'
    }
  }
})

<template>
  <main>
    <h1>Main Page Heading</h1>
    
    <section>
      <h2>Section</h2>
      <h3>Subsection</h3>
    </section>
    
    <aside>
      <h2>Sidebar</h2>
    </aside>
  </main>
</template>

<template>
  <header role="banner">
    <nav aria-label="Main Navigation">
      <!-- menu -->
    </nav>
  </header>
  
  <main role="main">
    <!-- main content -->
  </main>
  
  <aside role="complementary">
    <!-- supplementary content -->
  </aside>
  
  <footer role="contentinfo">
    <!-- footer -->
  </footer>
</template>

<template>
  <!-- Toggle button -->
  <button 
    :aria-expanded="isOpen"
    :aria-controls="panelId"
    @click="toggle"
  >
    Show Details
  </button>
  
  <div 
    :id="panelId"
    v-show="isOpen"
    role="region"
    aria-labelledby="toggle-btn"
  >
    Panel content
  </div>
</template>

<script setup lang="ts">
const headingRef = ref<HTMLElement | null>(null)

// Focus on the heading after navigation
onMounted(() => {
  headingRef.value?.focus()
})
</script>

<template>
  <h1 ref="headingRef" tabindex="-1">
    Page Title
  </h1>
</template>

<template>
  <a 
    href="#main-content" 
    class="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:bg-white focus:p-4"
  >
    Skip to main content
  </a>
  
  <header>
    <!-- navigation -->
  </header>
  
  <main id="main-content">
    <!-- content -->
  </main>
</template>

<script setup lang="ts">
import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'

const modalRef = ref<HTMLElement | null>(null)
const { activate, deactivate } = useFocusTrap(modalRef)

watch(() => props.open, (isOpen) => {
  if (isOpen) {
    activate()
  } else {
    deactivate()
  }
})
</script>

<template>
  <div 
    v-if="open"
    ref="modalRef"
    role="dialog"
    aria-modal="true"
    aria-labelledby="modal-title"
  >
    <h2 id="modal-title">Modal Title</h2>
    <!-- content -->
    <button @click="close">Close</button>
  </div>
</template>

<!-- app.vue -->
<template>
  <NuxtRouteAnnouncer />
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

<script setup lang="ts">
const announcement = ref('')

function addToCart(product: string) {
  // business logic
  announcement.value = `${product} added to cart`
  
  // clear after 5 seconds
  setTimeout(() => {
    announcement.value = ''
  }, 5000)
}
</script>

<template>
  <!-- Hidden container for announcements -->
  <div 
    aria-live="polite" 
    aria-atomic="true"
    class="sr-only"
  >
    {{ announcement }}
  </div>
  
  <button @click="addToCart('Product')">
    Add to Cart
  </button>
</template>

/* Example of sufficient contrast */
.good-contrast {
  color: #1a1a1a;        /* dark text */
  background: #ffffff;   /* white background */
  /* Contrast: 16.1:1 ✓ */
}

/* Insufficient contrast */
.bad-contrast {
  color: #767676;        /* gray text */
  background: #ffffff;   /* white background */
  /* Contrast: 4.48:1 — barely passes AA */
}

<template>
  <!-- Bad: only color indicates an error -->
  <input :class="{ 'border-red-500': hasError }">
  
  <!-- Good: color + icon + text -->
  <div>
    <input 
      :class="{ 'border-red-500': hasError }"
      :aria-invalid="hasError"
      aria-describedby="error-message"
    >
    <p v-if="hasError" id="error-message" class="text-red-500">
      <span aria-hidden="true">⚠️</span>
      Enter a valid email
    </p>
  </div>
</template>

npx nuxi module add @nuxt/ui

<template>
  <!-- Accessible dialog out of the box -->
  <UModal v-model="isOpen">
    <UCard>
      <template #header>
        Confirmation
      </template>
      
      <p>Are you sure?</p>
      
      <template #footer>
        <UButton @click="confirm">Yes</UButton>
        <UButton variant="ghost" @click="isOpen = false">
          Cancel
        </UButton>
      </template>
    </UCard>
  </UModal>
</template>

npm install reka-ui

<script setup lang="ts">
import { AccordionRoot, AccordionItem, AccordionTrigger, AccordionContent } from 'reka-ui'
</script>

<template>
  <AccordionRoot type="single" collapsible>
    <AccordionItem value="item-1">
      <AccordionTrigger>Question 1</AccordionTrigger>
      <AccordionContent>Answer 1</AccordionContent>
    </AccordionItem>
  </AccordionRoot>
</template>

npx shadcn-vue@radix init
npx shadcn-vue@radix add button dialog

npm install -D eslint-plugin-vuejs-accessibility

// eslint.config.js (ESLint 9+)
import pluginVueA11y from 'eslint-plugin-vuejs-accessibility'

export default [
  ...pluginVueA11y.configs['flat/recommended'],
  {
    rules: {
      'vuejs-accessibility/alt-text': 'error',
      'vuejs-accessibility/anchor-has-content': 'error',
      'vuejs-accessibility/click-events-have-key-events': 'error',
      'vuejs-accessibility/label-has-for': 'error'
    }
  }
]

npm install -D nuxt-a11y

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-a11y']
})