Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Utilities

VisuallyHidden

Visually hide text while keeping it available to assistive technology.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add visually-hidden

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
import VisuallyHidden from './components/ui/visually-hidden/VisuallyHidden.vue'
</script>

<template>
  <Button variant="outline">
    <span aria-hidden="true">×</span>
    <VisuallyHidden>Close panel</VisuallyHidden>
  </Button>
</template>

Set focusable only when the hidden content itself must enter the tab order.

When to use it

Icon button name

Keep a text label available to assistive technology when only an icon is visible.

Additional context

Add a short explanation that visual layout already conveys.

More examples

Named close button

A text node can name a button without displaying a second visible label.

Named close button
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
import VisuallyHidden from './components/ui/visually-hidden/VisuallyHidden.vue'
</script>

<template>
  <Button variant="outline">
    <span aria-hidden="true">×</span>
    <VisuallyHidden>Close panel</VisuallyHidden>
  </Button>
</template>

Table caption

A hidden caption keeps table context without consuming visual space.

Table caption
<script setup lang="ts">
import VisuallyHidden from './components/ui/visually-hidden/VisuallyHidden.vue'
</script>

<template>
  <table>
    <caption>
      <VisuallyHidden>Quarterly revenue by region</VisuallyHidden>
    </caption>
    <thead>
      <tr>
        <th scope="col">Region</th>
        <th scope="col">Revenue</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <th scope="row">North</th>
        <td>€120,000</td>
      </tr>
    </tbody>
  </table>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

VisuallyHidden

Complete API for VisuallyHidden
NameType or signatureDefaultWhat it does
asprop"div" | "span" | undefined"span"Choose the HTML element or Vue component used for this control.
focusablepropboolean | undefinedfalseSet focusable only when the hidden content itself must enter the tab order, such as a skip link styled by the consumer.
defaultslot{}OptionalContent shown inside VisuallyHidden.
Public type definitions
Public types
// packages/frameworks/vue/components/visually-hidden/types.ts
// ------- TYPES -------

export interface VisuallyHiddenProps {
  as?: 'span' | 'div'
  focusable?: boolean
}

Implementation notes

  • Use hidden text only when the visible UI supplies enough context for sighted readers.
  • Focusable hidden content is an exceptional case; leave focusable false for ordinary labels.

Accessibility and localization

  • Hidden text remains in the accessibility tree and can provide a control name or table context.

Source contract and editing guidance