accessible astro components
v3.0.1
A set of Accessible, easy to use, Front-end UI Components for Astro. Most of these components are used in the Accessible Astro Starter and the Accessible Astro Dashboard themes and they provide exemplary use cases for these components. As a bonus, these themes also have their own dedicated components (like keyboard accessible and responsive navigations) and many Design System utility classes, patterns and primitives (such as grids, buttons, lists, spacings, sizes and more).
Live preview
Run the following command in your project folder to get started:
npm install accessible-astro-components --save-devYou can import the different components from the package using the following import statement:
---
import { Accordion, AccordionItem, Card, Modal, ... } from 'accessible-astro-components'
---Skip to: Accordion, Breadcrumbs, Card, DarkMode, Media, Modal, Notification, Pagination, SkipLinks
Accordions are great for grouping big chunks of content into easier to scan headers which the user can expand when they want to read what is associated with that header. This component uses the native HTML <details> and <summary> elements for built-in accessibility and functionality.
Some (accessibility) features of the Accordion:
name propallow-discrete and allow-keywords on the ::details-content pseudo element---
import { Accordion, AccordionItem } from 'accessible-astro-components'
---
<Accordion>
<AccordionItem
title="First Item"
>
<p>Lorem ipsum dolor sit amet consectetur adipisicing elit.</p>
<a href="#">Tab to me!</a>
</AccordionItem>
<!-- Items in the same group will close others when opened -->
<AccordionItem
name="group1"
title="Second Item"
>
<p>Content for second item</p>
</AccordionItem>
<AccordionItem
name="group1"
title="Third Item"
>
<p>Content for third item</p>
</AccordionItem>
</Accordion>AccordionItem
title (required): The text shown in the accordion headername (optional): Group name for exclusive behavior - items with the same name will close others when openedchildren: The content shown when the accordion is expandedYou can apply your own styles by either setting the individual properties using :global(body .accordion__item) for example, or set up a global style tag and define your styles in there:
<style lang="scss" is:global>
body .accordion__wrapper {
background-color: purple;
&[open] {
background-color: peru;
}
}
</style>Breadcrumbs are a great way to help users navigate back to a previous page or section. They are also a great way to help screen reader users understand where they are in the website.
Some (accessibility) features of the Breadcrumbs:
aria-label="Breadcrumbs"<nav> element to tell screen readers users that this is a navigation element---
import { Breadcrumbs, BreadcrumbsItem } from 'accessible-astro-components'
---
<Breadcrumbs>
<BreadcrumbsItem
href="/"
label="Home"
/>
<BreadcrumbsItem
href="/blog"
label="Blog"
/>
<BreadcrumbsItem
currentPage={true}
label="My blog post"
/>
</Breadcrumbs>You can apply your own styles by either setting the individual properties using :global(body .breadcrumbs__item) for example, or set up a global style tag and define your styles in there:
<style lang="scss" is:global>
body .breadcrumbs__item {
li::after {
content: '>';
}
}
</style>Cards are usually used in groups. By wrapping them in an unordered list we provide screen reader users with shortcuts to lists and list items. Screen readers also let the users know how many items there are in a list. In the example below you'll find the structure using an unordered list and display: grid, making sure we leave enough of a gap between Cards on touch devices for people who find they have low accuracy when targeting items, including those with Parkinson's disease and rheumatism. Leaving a bigger gap makes it easier to scroll without accidentally activating a Cards link.
Some (accessibility) features of the Card:
<a> ::after pseudo element<h3> so it can be used in many contexts (<h2> would be too limitingmax-width is set to 70ch---
import { Card } from 'accessible-astro-components'
---
<ul>
<li>
<Card
url="/link-to-my-post"
img="/assets/post-cover.jpg"
title="My Awesome Post"
footer="Tony Stark"
>
Lorem ipsum dolor sit amet.
</Card>
</li>
<li>
<!-- ... -->
</li>
</ul>
<style lang="scss">
ul {
display: grid;
grid-template-columns: 1fr;
grid-gap: 4rem;
@media (min-width: 550px) {
grid-template-columns: repeat(2, 1fr);
grid-gap: 2rem;
}
@media (min-width: 950px) {
grid-template-columns: repeat(3, 1fr);
}
}
</style>You can apply your own styles by either setting the individual properties using :global(body .card) for example, or set up a global style tag and define your styles in there:
<style lang="scss" is:global>
body .card {
color: purple;
background-color: blue;
a {
color: gold;
}
}
// set your own image height
.card__image {
height: 10rem;
}
</style>DarkMode is a toggle button component to add and remove a class of .darkmode to the <body> based on the user's preference for either a light or dark color scheme. The user's preference is saved to the localStorage to preserve their choice for future visits.
Some (accessibility) features of the DarkMode:
aria-pressed to indicate to screen reader users whether the dark scheme is toggled or notaria-labelsaria-hidden to hide the icons for dark and light mode and uses the aria-labelss insteadcolor-scheme to light or dark based on the user's preference so you can use the light-dark() function in your CSSinitialMode (optional): Sets the initial color scheme. Accepts 'light', 'dark', or 'auto' (default: 'auto')
'light': Forces light mode on first visit'dark': Forces dark mode on first visit'auto': Uses system preferences on first visit---
import { DarkMode } from 'accessible-astro-components'
---
<!-- Uses system preferences by default -->
<DarkMode />
<!-- Forces dark mode on first visit -->
<DarkMode initialMode="dark" />
<!-- Forces light mode on first visit -->
<DarkMode initialMode="light" /><style lang="scss">
body.darkmode {
// define your dark color scheme
}
</style>Note: After the first visit, the user's chosen preference will be saved to localStorage and will take precedence over the initialMode setting.
Media is a very simple component used for <img> tags. It has a default empty alt tag which is required for non-decorative images. Should the image be descriptive, for example when there's no (complementary) text, then you should always write a good descriptive alt tag. The Media component also utilizes the loading="lazy" tag to optimize performance from the browsers side.
Some (accessibility) features of the Media:
alt tag which is always required for non descriptive images.---
import { Media } from 'accessible-astro-components'
---
<Media
classes="elevation-300 radius-large"
src="https://unsplash.com/photos/d0oYF8hm4GI"
alt="A tiny toy astronaut, sitting on a yellow toy moon"
/>Modals are windows that appear on top of the parent screen, usually disabling the use of the parent screen and demanding immediate action from the user. This component uses the native HTML <dialog> element for built-in accessibility and functionality, enhanced with smooth transitions.
Some (accessibility) features of the Modal:
<dialog> element for built-in accessibilityid and aria-labeledby@starting-style and allow-discrete---
import { Modal } from 'accessible-astro-components'
---
<button id="modal1-trigger">Modal 1</button>
<button id="modal2-trigger">Modal 2</button>
<Modal
triggerId="modal1-trigger"
title="Modal 1"
>
<p>Why hello, I be the <strong>first</strong> Modal.</p>
</Modal>
<Modal
triggerId="modal2-trigger"
title="Modal 2"
closeText="Cancel"
>
<p>Ah yes, and I be the <strong>second</strong> Modal.</p>
<!--
calls the closeModal() function, you can also use this
as a callback in your own function
-->
<button onclick="closeModal()">Confirm action</button>
</Modal>You can apply your own styles by either setting the individual properties using :global(body .modal) for example, or set up a global style tag and define your styles in there:
<style lang="scss" is:global>
body {
.modal {
color: purple;
background-color: gold;
}
.modal__inner {
border-color: orange;
}
.modal__content {
gap: 1.5rem;
padding: 1rem;
}
.modal__close button {
color: white;
background-color: blue;
&:hover,
&:focus {
background-color: green;
}
}
}
</style>Notifications are often used to keep the user updated about changing state on a website or application. They can also be used as a general way to display some highlighted information in an article for example. There are two rules of thumb when it comes to Notifications and those are to always add contextual information about the Notification (such as starting with "Tip:", "Info:", "Error:") and when adding a Notification to the DOM in response to a user action, you should always use role="status" and aria-live="polite" to inform screen reader users. To add some extra visuals you can combine the Notification component with Astro Icon.
Some (accessibility) features of the Notification:
role="status" and aria-live="polite"---
import { Notification } from 'accessible-astro-components'
---
<Notification
type="info"
>
<p><strong>Info:</strong> This is a notification of type info.</p>
</Notification>
<!-- example using Astro Icon -->
<Notification
type="info"
>
<Icon pack="ion" name="information-circle-outline" /><p><strong>Info:</strong> This is a notification of type info.</p>
</Notification>
<!-- when added to the DOM after a user interaction -->
<Notification
type="info"
role="status"
aria-live="polite"
>
<p><strong>Info:</strong> This is a notification of type info.</p>
</Notification>You can apply your own styles by either setting the individual properties using :global(body .notification) for example, or set up a global style tag and define your styles in there:
<style lang="scss" is:global>
body {
.notification {
color: var(--neutral-900, #202427);
background-color: var(--neutral-200, #f6f8f9);
border: 2px solid var(--neutral-600, #858d93);
&.type-info {
color: var(--info-900, #035486);
background-color: var(--info-100, #e0f7ff);
border-color: var(--info-600, #1a91d1);
}
&.type-success {
color: var(--success-900, #014b3e);
background-color: var(--success-100, #eefcf6);
border-color: var(--success-500, #28a980);
}
&.type-warning {
color: var(--warning-900, #8e2a0b);
background-color: var(--warning-100, #fffbeb);
border-color: var(--warning-600, #dc901e);
}
&.type-error {
color: var(--error-900, #5e0317);
background-color: var(--error-100, #ffe0e0);
border-color: var(--error-500, #df2a39);
}
}
}
</style>A fairly simple yet effective Pagination component which has a first, previous, next, and last page button. It also tells the user how many pages there are and what page they are currently on. The Pagination component is also fully accessible and keyboard navigable.
Some (accessibility) features of the Pagination:
aria-labels to tell the user whether they will go to the previous or next page and which page numberaria-hidden to hide the icons for the previous and next pages---
import { Pagination } from 'accessible-astro-components'
---
<Pagination
firstPage="/1"
previousPage="/4"
nextPage="/6"
lastPage="/10"
currentPage="/5"
totalPages="10"
/>---
import { Pagination } from 'accessible-astro-components'
export async function getStaticPaths({ paginate }) {
const response = await fetch('https://jsonplaceholder.typicode.com/posts')
const data = await response.json()
return paginate(data, { pageSize: 6 })
}
const { page } = Astro.props
---
<Pagination
firstPage={page.url.prev ? '/blog' : null}
previousPage={page.url.prev ? page.url.prev : null}
nextPage={page.url.next ? page.url.next : null}
lastPage={page.url.next ? `/blog/${Math.round(page.total / page.size)}` : null}
currentPage={page.currentPage}
totalPages={Math.round(page.total / page.size)}
/>You can apply your own styles by either setting the individual properties using :global(body .pagination) for example, or set up a global style tag and define your styles in there:
<style lang="scss" is:global>
body .pagination a {
svg path {
stroke: gold;
}
&:hover,
&:focus-visible {
background-color: purple;
svg path {
stroke: white;
}
}
.disabled {
border-color: red;
opacity: 0.1;
}
}
</style>SkipLinks provide a way for users using assistive technologies to skip repeated content on pages to go directly to the main content of a website or application. To use this component properly, make sure you give the main content of your project an id of #main-content so that the SkipLink can target it. As a fallback the SkipLink will try to target the h1 of the page. If neither are found a warning will be logged to the console.
Some (accessibility) features of the SkipLinks:
---
import { SkipLinks } from 'accessible-astro-components'
---
<SkipLinks />You can apply your own styles by either setting the individual properties using :global(body .skiplinks) for example, or set up a global style tag and define your styles in there:
<style lang="scss" is:global>
body .skiplinks a {
color: white;
background-color: purple;
&:hover
&:focus {
background-color: indigo;
}
}
</style>A fully accessible tabs component that follows WAI-ARIA guidelines. Tabs are a great way to organize content into different sections, allowing users to switch between them easily.
Some (accessibility) features of the Tabs:
id, aria-controls and aria-labelledby---
import { Tabs, TabsList, TabsPanel, TabsTab } from 'accessible-astro-components'
---
<Tabs>
<TabsList>
<TabsTab id="tab1" controls="panel1" selected>Tab 1</TabsTab>
<TabsTab id="tab2" controls="panel2">Tab 2</TabsTab>
<TabsTab id="tab3" controls="panel3">Tab 3</TabsTab>
</TabsList>
<TabsPanel id="panel1" labelledby="tab1" selected>
<h2>Panel 1</h2>
<p>Content for first panel</p>
</TabsPanel>
<TabsPanel id="panel2" labelledby="tab2">
<h2>Panel 2</h2>
<p>Content for second panel</p>
</TabsPanel>
<TabsPanel id="panel3" labelledby="tab3">
<h2>Panel 3</h2>
<p>Content for third panel</p>
</TabsPanel>
</Tabs>Tabs
class - Optional string for additional CSS classesTabsList
class - Optional string for additional CSS classesTabsTab
id - Required string for unique tab identificationcontrols - Required string matching the panel ID this tab controlsselected - Optional boolean to set initial selected stateclass - Optional string for additional CSS classesTabsPanel
id - Required string for unique panel identificationlabelledby - Required string matching the tab ID that labels this panelselected - Optional boolean to set initial selected stateclass - Optional string for additional CSS classesYou can apply your own styles by either setting the individual properties using :global(body .tabs) for example, or set up a global style tag and define your styles in there:
<style lang="scss" is:global>
body .tabs-list {
background-color: purple;
}
</style>If you find that something isn't working right then I'm always happy to hear it to improve these components! You can contribute in many ways and forms. Let me know by either:
I'd like to extend my gratitude to the creators of Astro and all those who have utilized these components and shared valuable insights to enhance web accessibility worldwide. Additionally, I'd like to acknowledge the contributions of notable figures in the web development community, including Zell Liew from Learn JavaScript Today and Heydon Pickering, the author of Inclusive Components, among others. Special thanks go out to all the contributors to this repository, with particular recognition for David Abell, whose substantial contributions, such as the addition of TypeScript support, have greatly benefited the project. Your collective efforts are highly appreciated!
