Many Web Awesome components are open source, meaning everyone can use them and contribute to their development. When you join our community, you'll find a friendly group of enthusiasts at all experience levels who are willing to chat about anything and everything related to Web Awesome.
The easiest way to get started contributing is to join the community chat. This is where we hang out, discuss new ideas, ask for feedback, and more!
A common misconception about contributing to an open source project is that you need to know how to code. This simply isn't true. In fact, there are many ways to contribute, and some of the most important contributions come from those who never write a single line of code. Here's a list of ways you can make a meaningful contribution to the project:
Please take a moment to review these guidelines to make the contribution process as easy as possible for both yourself and the project's maintainers.
As an open source maintainer, I respectfully ask that you refrain from using AI-generated code when contributing to this project. This includes code generated by tools such as GitHub Copilot, even if you make alterations to it afterwards. While some of Copilot's features are indeed convenient, the ethics surrounding which codebases the AI has been trained on and their corresponding software licenses remain very questionable and have yet to be tested in a legal context.
I realize that one cannot reasonably enforce this any more than one can enforce not copying licensed code from other codebases, nor do I wish to expend energy policing contributors. I would, however, like to avoid all ethical and legal challenges that result from using AI-generated code. As such, I respectfully ask that you refrain from using such tools when contributing to this project. At this time, I will not knowingly accept any code that has been generated in such a manner.
The issue tracker is for bug reports, feature requests, and pull requests.
Issues that do not follow these guidelines are subject to closure. There simply aren't enough resources for the author and contributors to troubleshoot personal support requests.
Feature requests can be added using the discussion forum.
A bug is a demonstrable problem caused by code in the library. Bug reports are an important contribution to the quality of the project. When submitting a bug report, there are a few steps you can take to make sure your issues gets attention quickly.
A minimal test case is critical to a successful bug report. It demonstrates that the bug exists in the library and not in surrounding code. Contributors should be able to understand the bug without studying your code, otherwise they'll probably move on to another bug.
To keep the project on track, please consider the following guidelines before submitting a PR.
next branch.dist/. These files are generated automatically,
so you need to edit the source files instead.
The author reserves the right to reject any PR that's outside the scope of the project or doesn't meet code quality standards.
current - This branch reflects the latest release.
next - This is the branch you should submit pull requests against. It reflects what's coming in
the next release.
Maintaining good documentation can be a painstaking task, but poor documentation leads to frustration and makes the project less appealing to users. Fortunately, writing documentation for Web Awesome is fast and easy!
Most of Web Awesome's technical documentation is generated with JSDoc comments and TypeScript metadata from the source code. Every property, method, event, etc. is documented this way. In-code comments encourage contributors to keep the documentation up to date as changes occur so the docs are less likely to become stale. Refer to an existing component to see how JSDoc comments are used in Web Awesome.
Instructions, code examples, and interactive demos are hand-curated to give users the best possible experience. Typically, the most relevant information is shown first and less common examples are shown towards the bottom. Edge cases and gotchas should be called out in context with tips or warnings.
The docs are powered by Eleventy. Check out
docs/components/*.md to get an idea of how pages are structured and formatted. If you're creating
a new component, it may help to use an existing component's markdown file as a template.
If you need help with documentation, feel free to reach out on the community chat.
The Web Awesome documentation uses an extended version of markdown-it. Generally speaking, it follows the Commonmark spec while sprinkling in some additional features.
To render a code preview, use the standard code field syntax and append :preview to the language.
```html {.example} [code goes here] ```
You can also append .open to expand the code by default, and .no-edit to disable the
CodePen button. The order of these modifiers doesn't matter, but no spaces should exist between the language
and the modifiers.
```html {.example .open .no-edit} [code goes here] ```
This particular syntax was chosen for a few reasons:
Special callouts can be added using the following syntax.
:::info This is a tip/informational callout ::: :::warning This is a caution callout :::
To link to a GitHub issue, PR, or discussion, use the following syntax.
[#1234]
The following is a non-exhaustive list of conventions, patterns, and best practices we try to follow. As a contributor, we ask that you make a good faith effort to follow them as well. This ensures consistency and maintainability throughout the project.
If in doubt, use your best judgment and the maintainers will be happy to guide you during the code review process. If you'd like clarification on something before submitting a PR, feel free to reach out on the community chat.
This section can be a lot to digest in one sitting, so don't feel like you need to take it all in right now. Most contributors will be better off skimming this section and reviewing the relevant content as needed.
Web Awesome is built with accessibility in mind. Creating generic components that are fully accessible to users with varying capabilities across a multitude of circumstances is a daunting challenge. Oftentimes, the solution to an a11y problem is not written in black and white and, therefore, we may not get it right the first time around. There are, however, guidelines we can follow in our effort to make Web Awesome an accessible foundation from which applications and websites can be built.
We take this commitment seriously, so please ensure your contributions have this goal in mind. If you need help with anything a11y-related, please reach out to the community for assistance. If you discover an accessibility concern within the library, please file a bug on the issue tracker.
It's important to remember that, although accessibility starts with foundational components, it doesn't end with them. It everyone's responsibility to encourage best practices and ensure we're providing an optimal experience for all of our users.
Most code formatting is handled automatically by Prettier via commit hooks. However, for the best experience, you should install it in your editor and enable format on save.
Please do not make any changes to prettier.config.cjs without consulting the maintainers.
Components should be composable, meaning you can easily reuse them with and within other components. This reduces the overall size of the library, expedites feature development, and maintains a consistent user experience.
All components have a host element, which is a reference to the <wa-*> element itself. Make
sure to always set the host element's display property to the appropriate value depending on your
needs, as the default is inline per the custom element spec.
:host { display: block; }
Aside from display, avoid setting styles on the host element when possible. The reason for this
is that styles applied to the host element are not encapsulated. Instead, create a base element that wraps the
component's internals and style that instead. This convention also makes it easier to use BEM in components,
as the base element can serve as the "block" entity.
When authoring components, please try to follow the same structure and conventions found in other components. Classes, for example, generally follow this structure:
@query decorators@state decorators@property decoratorsconnectedCallback(), disconnectedCallback(),
firstUpdated(), etc.)
@watch decoratorsrender() method
Please avoid using the public keyword for class fields. It's simply too verbose when combined
with decorators, property names, and arguments. However, please do add private in front
of any property or method that is intended to be private.
This might seem like a lot, but it's fairly intuitive once you start working with the library. However, don't let this structure prevent you from submitting a PR. Code can change and nobody will chastise you for "getting it wrong." At the same time, encouraging consistency helps keep the library maintainable and easy for others to understand. (A lint rule that helps with things like this would be a very welcome PR!)
All components use a shadow DOM, so styles are completely encapsulated from the rest of the document. As a result, class names used inside a component won't conflict with class names outside the component, so we're free to name them anything we want.
Internally, each component uses the BEM methodology for class names. There is no technical requirement to do this — it's purely the preference of the author to enforce consistency and clarity throughout components. As such, all contributions are expected to follow this pattern.
Boolean props should always default to false, otherwise there's no way for the user to
unset them using only attributes. To keep the API as friendly and consistent as possible, use a property such
as noValue and a corresponding kebab-case attribute such as no-value.
When naming boolean props that hide or disable things, prefix them with no-, e.g.
no-spin-buttons and avoid using other verbs such as hide- and
disable- for consistency.
When a component relies on the presence of slotted content to do something, don't assume its initial state is permanent. Slotted content can be added or removed any time and components must be aware of this. A good practice to manage this is:
@slotchange={this.handleSlotChange} to the slots you want to watchhandleSlotChange method and use the hasSlot utility to update state
variables for the the respective slot(s)
<slot> elements in a component — always use
hidden so the slot remains in the DOM and the slotchange event can be captured
See the source of card, dialog, or drawer for examples.
A pattern has been established in <wa-details> and <wa-tree-item> for
expand/collapse icons that animate on open/close. In short, create two slots called
expand-icon and collapse-icon and render them both in the DOM, using CSS to
show/hide only one based on the current open state. Avoid conditionally rendering them. Also avoid using
dynamic slot names, such as <slot name=${open ? 'open' : 'closed'}>, because Firefox will
not animate them.
There should be a container element immediately surrounding both slots. The container should be animated with
CSS by default and it should have a part so the user can override the animation or disable it. Please refer to
the source and documentation for <wa-details> and/or <wa-tree-item> for
details.
When providing fallback content inside of <slot> elements, avoid adding parts, e.g.:
<slot name="icon"> <wa-icon part="close-icon"></wa-icon> </slot>
This creates confusion because the part will be documented, but it won't work when the user slots in their own content. The recommended way to customize this example is for the user to slot in their own content and target its styles with CSS as needed.
Components must only emit events that start with wa- as a namespace. For compatibility with
frameworks that utilize DOM templates, events must have lowercase, kebab-style names. For example, use
wa-change instead of waChange.
This convention avoids the problem of browsers lowercasing attributes, causing some frameworks to be unable to listen to them. This problem isn't specific to one framework, but Vue's documentation provides a good explanation of the problem.
When change events are emitted by Web Awesome components, they should be named wa-change and they
should only be emitted as a result of user input. Programmatic changes, such as setting
el.value = '…' should not result in a change event being emitted. This is consistent
with how native form controls work.
Custom properties allow users to customize Web Awesome components by exposing specific styles across a component's shadow boundary. Use custom properties to expose key characteristics of a component for low-level theming. Avoid using custom properties for styles that may interfere with proper rendering.
To expose custom properties as part of a component's API, scope them to the :host block.
:host { --color: var(--wa-color-brand-on-loud); --background-color: var(--wa-color-brand-fill-loud); }
Then use the following syntax for comments so they appear in the generated docs. Do not use the
--wa- prefix, as that is reserved for design tokens that live in the global scope.
/** * @cssproperty --color: The component's text color. * @cssproperty --background-color: The component's background color. */ export default class WaExample { // ... }
When an item within a keyboard navigable set is disabled (e.g. tabs, trees, menu items, etc.), the disabled item should not receive focus via keyboard, click, or tap. It should be skipped just like in operating system menus and in native HTML form controls. There is no exception to this. If a particular item requires focus for assistive devices to provide a good user experience, the item should not be disabled and, upon activation, it should inform the user why the respective action cannot be completed.
When designing a component's API, standard properties are generally used to change the behavior of a component, whereas CSS custom properties ("CSS variables") are used to change the appearance of a component. Remember that properties can't respond to media queries, but CSS variables can.
There are some exceptions to this (e.g. when it significantly improves developer experience), but a good rule of thumbs is "will this need to change based on screen size?" If so, you probably want to use a CSS variable.
There are two ways to enable customizations for components. One way is with CSS custom properties ("CSS variables"), the other is with CSS parts ("parts").
CSS variables are scoped to the host element and can be reused throughout the component. A good example of a
CSS variable would be --border-width, which might get reused throughout a component to ensure
borders share the same width for all internal elements.
Parts let you target a specific element inside the component's shadow DOM but, by design, you can't target a part's children or siblings. You can only customize the part itself. Use a part when you need to allow a single element inside the component to accept styles.
This convention can be relaxed when the developer experience is greatly improved by not following these suggestions.
While CSS parts can be named virtually anything, within Web Awesome they must use the kebab-case convention and lowercase letters. Additionally, a BEM-inspired naming convention is used to distinguish parts, subparts, and states.
When composing elements, use part to export the host element and exportparts to
export its parts.
render() { return html` <div part="base"> <wa-icon part="icon" exportparts="base:icon__base" ...></wa-icon> </div> `; }
This results in a consistent, easy to understand structure for parts. In this example, the
icon part will target the host element and the icon__base part will target the
icon's base part.
TL;DR – a component is a dependency if and only if it's rendered inside another component's shadow root.
Many Web Awesome components use other Web Awesome components internally. For example,
<wa-button> uses both <wa-icon> and <wa-spinner> for
its caret icon and loading state, respectively. Since these components appear in the button's shadow root,
they are considered dependencies of Button. Since dependencies are automatically loaded, users only need to
import the button and everything will work as expected.
Contrast this to <wa-select> and <wa-option>. At first, one might assume
that Option is a dependency of Select. After all, you can't really use Select without slotting in at least one
Option. However, Option is not a dependency of Select! The reason is because no Option is rendered in
the Select's shadow root. Since the options are provided by the user, it's up to them to import both
components independently.
People often suggest that Web Awesome should auto-load Select + Option, Menu + Menu Item, Breadcrumb + Breadcrumb Item, etc. Although some components are designed to work together, they're technically not dependencies so eagerly loading them may not be desirable. What if someone wants to roll their own component with a superset of features? They wouldn't be able to if Web Awesome automatically imported it!
Similarly, in the case of <wa-radio-group> there was originally only
<wa-radio>, but now you can use either <wa-radio> or
<wa-radio-button> as child elements. Which component(s) should be auto-loaded dependencies
in this case? Had Radio been a dependency of Radio Group, users that only wanted Radio Buttons would be forced
to register both with no way to opt out and no way to provide their own customized version.
For non-dependencies, the user should decide what gets registered, even if it comes with a minor inconvenience.
Form controls should support submission and validation through the following conventions:
WebAwesomeFormAssociatedElementname, value, and disabled properties in
the same manner as HTMLInputElement
disabled property NOT reflect the
disabled attribute.
invalid property that reflects their validityrequired,
pattern, minlength, maxlength, etc. when possible and use the
MirrorValidator.
<form> element@property({ reflect: true }) value
@property({ attribute: false }) value and
@property({ attribute: "value", reflect: true }) defaultValue. We do this to align
with how native form controls work.
checked or selected should
also have a defaultSelected and defaultChecked property respectively for use when
the form is "reset".
Avoid inlining SVG icons inside of templates. If a component requires an icon, make sure
<wa-icon> is a dependency of the component and use the
system library:
<wa-icon library="system" name="..." variant="..."></wa-icon>
This will render the icons instantly whereas the default library will fetch them from a remote source. If an
icon isn't available in the system library, you will need to add it to library.system.ts. Using
the system library ensures that all icons load instantly and are customizable by users who wish to provide a
custom resolver for the system library.
What to test for a given component:
const myComponent = await fixture<WaComponent>(html`<wa-component>...</wa-component>`); await expect(myComponent).to.be.accessible();
Guidelines for writing tests:
Right now, tests run both "hydrated" (SSR -> client hydrated) and "client only". If you're debugging only one specific kind you can set an environment variable. For example, to run only the client tests, you can do:
CSR_ONLY="true" npm run test
or for hydrated rendering only:
SSR_ONLY="true" npm run test