Alert dialog for confirming or canceling actions.

Clicking on the outside or pressing the escape key will close the dialog and that counts as canceling.

Slot default is used as the content of the alert, and also becomes the ARIA description of the alert.

This is a minimal header meant for web apps where a full Illinois brand header would be too large.

Slot left allows replacing the link element in the top-left corner.

Slot title is to the right of the logo.

Slot navigation shows a short set of main navigation links. On small screens it automatically switches to a popover menu.

Slot app-controls is the remaining area to the right.

The element or component can be set with the component prop, so it can be a link or router-link component from vue-router. For example:

<GButton component="router-link" to="/some-route">
    Click me
</GButton>

Note that grad-vue doesn't include vue-router as a dependency.

Icons can be added with either the icon prop or a named slot icon:

• Use the icon prop to pass an icon class string, e.g., "fa-solid fa-plus".
• If using the icon prop, the icon will be rendered as a span with the aria-hidden attribute set to true.
• Use a named slot icon to provide custom icon content.
• If both icon prop and named slot icon are provided, the named slot takes precedence.

A group of checkboxes (or radio buttons) with styling for a label, instructions, and error messages.

When more than one option is provided (or radio mode is used), a fieldset + legend provides semantic grouping. With a single checkbox a plain div is rendered instead.

Each option renders as a native <input type="checkbox"> (or type="radio" when radio is true) so that keyboard navigation and browser/assistive-technology support come for free.

In standard Vue usage, this registers with the nearest parent GForm via injection. In custom-elements mode, use matching form-key values to pair with a GForm.

Errors are provided as an array of strings or computed values. Multiple errors will all be displayed.

Displays text with a clipboard button that copies the text to the clipboard. The text can be hidden in cases where it's already displayed differently.

If for some reason the user's browser doesn't support a clipboard, the tooltip will indicate that when they try to copy.

A form wrapper component that automatically manages form state and connects to child input components.

Child input components that have a name prop will automatically register with the form, and their values will be tracked in the form model.

Features

• Automatic value tracking for child input components with the name prop
• Reactive error handling by providing a computed list of errors
• Optionally manage your own form state in a parent component by providing a form injection
• In web components mode, use the form-key prop to pair a form with matching inputs/buttons across custom element app boundaries

Basic example

<GForm v-model="formData" @submit="handleSubmit">
  <template #default="{ isSubmitting, hasErrors }">
    <GTextInput name="firstName" label="First Name" :errors="firstNameErrors" />
    <GSubmitButton :disabled="hasErrors">Submit</GSubmitButton>
  </template>
</GForm>

A scroller that is used for content that's typically shown like a chat log, meaning it starts at the bottom, and you scroll up for older entries.

The scroller automatically starts at the bottom. When scrolled up, a button appears that jumps to the bottom. This button is also the first focusable element for accessibility.

If the label is provided, the scroller will have the ARIA role="log" and the label as the aria-label.

Slot default is what will be rendered for each entry in the entries. For example:

<GHistoryScroller
    v-bind="props"
    :entries="historyEntries"
    class="history-scroller">
    <template #default="{ entry }">
        <div class="history-entry">
            This is history for: {{ entry.id }}
        </div>
    </template>
</GHistoryScroller>

Generic modal component.

Clicking on the outside or pressing the escape key will close the modal.

Props:

• label: Modal accessible label.
• describedby: Element ID to pass to aria-describedby. Use this if there's specific important text to describe the modal.
• hiddenLabel: Hide label visually. It will still be used as aria-label.
• size: Modal size

Slot default is used as the content of the modal.

When the modal is opened, focus is placed on the H2 label element. This can be overridden by providing a popover-focus attribute on an element inside the modal.

Adding a dimming overlay behind modals can be done by placing GOverlay at the end of the page structure.

A multi-select combobox that allows selecting multiple values with optional search/filter support.

Selected values are displayed as removable chips inside the control. The dropdown listbox shows all (or filtered) options with a checkmark next to each selected option.

The options prop accepts an array of strings or { label, value } objects. Options may also include an optional description, which renders as a smaller second line beneath the label in the dropdown. Selected chips only show the label (first part) to keep the control compact. The search filter matches both the label and the description; set searchDescription to false to match on the label only. The v-model binds to an array of string | number values.

In standard Vue usage, this registers with the nearest parent GForm via injection. In custom-elements mode, use matching form-key values to pair with a GForm.

Keyboard navigation:

• Down Arrow / Up Arrow: move through options (opens menu if closed)
• Enter: toggle the focused option
• Space: toggle the focused option when the search field is empty
• Escape: close the dropdown
• Home / End: jump to first / last option
• Backspace: remove the last chip when the search field is empty

Popover that appears next to or over a trigger element, staying visible in the viewport as much as possible.

Slot trigger is optional. When provided, it should contain an interactive element for opening the popover and it is used for aria-labelledby. The trigger is passed a prop toggle which is a function that toggles the popover's open state, open for its current state, and popoverId for linking the trigger to the dialog with aria-controls.

Without a trigger slot, open the popover programmatically via show() or toggle() on the component instance / custom element.

Slot default is the content of the popover.

Example:

<GPopover>
    <template #trigger="{ toggle }">
        <GButton @click="toggle">
            Can Popovers have Popovers?
        </GButton>
    </template>
    <div>In theory, but I wouldn't recommend it.</div>
</GPopover>

A component that can show progress from 1 to 100 or an indeterminate spinner. If a value is omitted, the progress will be indeterminate.

If no label is specified, the default accessible label will be "Loading".

If a value is provided, the element will have the ARIA role progressbar with the appropriate ARIA value attributes.

If no value is provided, the element will have the ARIA role status.

A combobox-style search that shows a list of results as an auto complete dropdown.

The component doesn't perform any real searching. It emits events that can be used to trigger searches, and then the results are passed back to the component.

Events:

• submit event is emitted when a search should be performed.
• select event is submitted when a user makes a selection in the dropdown.

Props:

• results will be rendered in the dropdown. There are two options:
  • Pass an array of objects that extend { id: string | number; title: string; }.
  • Pass an array of GSearchGroup<T> objects, where the items property extends the above type. In this case the results are grouped.
• auto makes search submit on user input. Defaults to true. if false, submission happens on Enter or clicking the search button.
• loading shows a loading indicator. Use if the search may take longer.

Slot: option customizes how an option is rendered. It receives the current item as option.

Slot: group customizes the group label for each group.

Here is a minimal implementation:

<script setup lang="ts">
interface SearchResult {
    id: string;
    title: string;
}

const searchData = ref<SearchResult[]>([
    { id: "1", title: "The Quick Fox" },
    { id: "2", title: "The Lazy Dog" },
    { id: "3", title: "The Brown Bear" },
]);
const searchResults = ref<SearchResult[]>([]);

function submit(query: string) {
    searchResults.value = searchData.value.filter((result) =>
        result.title.toLowerCase().includes(query.toLowerCase()),
    );
}
function selected(item: SearchResult) {
    console.log("Selected:", item);
}
</script>
<template>
    <GSearch
        :results="searchResults"
        @submit="submit"
        @select="selected">
    </GSearch>
</template>

By default, this component behaves like a normal select element with custom styling.

In standard Vue usage, this registers with the nearest parent GForm via injection. In custom-elements mode, use matching form-key values to pair with a GForm.

The component can be marked searchable to enable search functionality. This turns it into a text input that filters the options. Filtering is done with a simple lower-case string search that matches both the option label and its description. Set searchDescription to false to match on the label only.

The options prop can be an array of strings or objects with label and value properties. Options may also include an optional description, which renders as a smaller second line beneath the label in the dropdown to give extra context (for example a code and its full name).

This component is just a radio button group with special styling.

In standard Vue usage, this registers with the nearest parent GForm via injection. In custom-elements mode, use matching form-key values to pair with a GForm.

Use the options prop to provide a list of choices. Each option can be a string or an object with label and value properties.

In addition to v-model, a change event is emitted when the option changes from user interaction.

A simple sidebar that's fixed to the left side of the viewport.

This includes the CSS for the fixed position and sizing, so the element should be fairly high in the DOM tree.

If neither top-offset nor top-offset-var are defined, the sidebar will be offset by var(--g-toolbar-height). If there is no toolbar, just pass 0 as the top-offset.

The sidebar can be made collapsible by providing the sidebar injected object from useSidebar. See the Hamburger Menu Documentation for details.

In web components mode, use the sidebar-key prop to pair this sidebar with a matching GHamburgerMenu instance and media-query to set the collapsible breakpoint.

When storage-key is provided, the sidebar remembers and restores its own scroll position from sessionStorage.

The dark theme has no background image by default. Set the --g-sidebar-background-image CSS variable (or the background-image prop) to add one.

A sidebar menu component for use with GSidebar. Displays a title and a list of links.

This component also supports showing active links for in-page navigation.

Props:

• items with a list of MenuItem objects. The objects should have:
  • label for the link text
  • href or to for the destination. If to is used, the links will be rendered as router-link for vue-router.
• spy to enable tracking active links for in-page navigation
• offset to adjust the active link tracking position
• theme to set the menu theme

For tracking the active link, the spy prop must be set to true and a v-model must be provided that has the ID of the target element (without #).

The composable function useActiveLinkContent can be used to track active links. It takes the following parameters:

• Ref<HTMLElement> Children of this element will be observed
• number Offset from the top of the window to consider not visible
• Ref<string> Ref to store the active element ID

The direct children of the element must all have an ID to properly work with in-page navigation, and the matching menu item's href should be set to #<id>.

Here's a minimal example of a page using useActiveLinkContent:

<script setup lang="ts">
import { computed, onMounted, ref, useTemplateRef } from "vue";
import { useActiveLinkContent } from "@illinois-grad/grad-vue";

const activeId = ref<string>("");
const main = useTemplateRef("main");
// onMounted is for Nuxt compatibility
onMounted(() => {
    useActiveLinkContent(main, 70, activeId);
});
</script>

<template>
  <GSidebar>
      <GSidebarMenu
          :items="[
              { label: 'Buttons', href: '#buttons' },
              { label: 'More Buttons', href: '#more-buttons' }
          ]"
          v-model="activeId"
      />
  </GSidebar>
  <main class="main" ref="main">
      <section id="buttons">
          <h2>Buttons</h2>
          <p>Some buttons</p>
      </section>
      <section id="more-buttons">
          <h2>More Buttons</h2>
          <p>Some more buttons</p>
      </section>
  </main>
</template>

A text input with styling for a label, instructions, and error messages.

If label is omitted, an accessible label must be provided some other way. All non-prop attributes are passed through to the input element, including id.

In standard Vue usage, this registers with the nearest parent GForm via injection. In custom-elements mode, use matching form-key values to pair with a GForm.

Errors are provided as an array of strings or computed values. Multiple errors will all be displayed.

A multi-line plain text input with styling for a label, instructions, and error messages.

If label is omitted, an accessible label must be provided some other way. All non-prop attributes are passed through to the textarea element, including id.

In standard Vue usage, this registers with the nearest parent GForm via injection. In custom-elements mode, use matching form-key values to pair with a GForm.

Errors are provided as an array of strings or computed values. Multiple errors will all be displayed.

A hierarchical sidebar menu component suitable for book-like or nested-section navigation. Items with children start collapsed and can be expanded/collapsed individually.

Links are authored directly in HTML for progressive enhancement — the page works as a basic list of links even without JavaScript.

Use GTreeMenuList and GTreeMenuItem sub-components to build the menu:

<GTreeMenu heading="Contents">
    <GTreeMenuList>
        <GTreeMenuItem label="Chapter 1">
            <a href="#ch1">Chapter 1</a>
            <template #children>
                <GTreeMenuItem><a href="#s1">Section 1.1</a></GTreeMenuItem>
            </template>
        </GTreeMenuItem>
    </GTreeMenuList>
</GTreeMenu>

Props:

• heading - optional heading and accessible name for the nav landmark.
• listType - ul (default) or ol. Use ol for numbered hierarchies such as book chapters. Inherited by nested GTreeMenuList components via provide/inject.
• theme - light (default) or dark.
• storageKey - when provided, expanded/collapsed states are persisted to sessionStorage under this key and restored on page load. This is useful in Web Component / Drupal contexts where every page navigation is a full refresh. Item states are keyed by the item's label prop.

A "skip to main content" link for keyboard and screen reader users.

Place it as the first focusable element in the app, before GAppHeader. It stays hidden until it receives keyboard focus. Activating it moves focus to the element with the target id (usually a GMain), falling back to the first <main> element.

Focus is moved with JavaScript, so it works with client-side routers and with targets that are rendered after the link.

<GSkipLink />
<GAppHeader>...</GAppHeader>
<RouterView />

The <main> landmark for a page, set up as the target for GSkipLink and useRouteAnnouncer.

Use one per page, inside each view rather than around <RouterView>, so sidebars and other complementary content stay outside the landmark.

<template>
    <GSidebar>...</GSidebar>
    <GMain class="profile">
        <h1>Profile</h1>
    </GMain>
</template>

Accessible route changes

Use the useRouteAnnouncer composable once in the root component. After each navigation to a different page, it moves focus to the <h1> inside GMain (or GMain itself) and announces the new page title. Navigations that only change the query or hash are ignored.

// App.vue setup
import { useRouter } from "vue-router";
import { useRouteAnnouncer } from "@illinois-grad/grad-vue";

useRouteAnnouncer(useRouter());

<GSkipLink />
<GAppHeader>...</GAppHeader>
<RouterView />

Options can customize what counts as a new page (isNewPage), when focus moves (focus), waiting for async page data (ready), and the announcement text (message).