# shiny.webawesome

`shiny.webawesome` provides an R and [Shiny](https://shiny.posit.co)
interface to the [Web Awesome](https://webawesome.com) component
library.

The package is largely generated from the upstream Web Awesome metadata
file `custom-elements.json`, which the package treats as the primary
source of truth for component wrappers and related generated surface. It
also bundles the Web Awesome runtime it needs, so package users do not
need to install Web Awesome assets separately in their Shiny apps. To
report the bundled Web Awesome version in your current installation, use
[`wa_version()`](https://www.shiny-webawesome.org/reference/wa_version.md).

The package design aims to stay as close as practical to upstream Web
Awesome names, conventions, and component APIs, while adopting normal R
naming conventions such as `snake_case`. Because Web Awesome lives in
the browser and Shiny spans both server and client, the package also
includes a curated set of Shiny bindings plus a narrow helper/command
layer for cases where a pure wrapper mirror is not enough.

See the package documentation for the details of the generated wrapper
surface, Shiny bindings, and advanced browser-glue helpers.

## Installation

To install from CRAN, use either of the following:

``` r
install.packages("shiny.webawesome")
```

``` r
pak::pak("shiny.webawesome")
```

To install the development version from GitHub, use either of the
following:

``` r
pak::pak("mbanand/shiny.webawesome")
```

``` r
remotes::install_github("mbanand/shiny.webawesome")
```

## Usage

``` r
library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "shiny.webawesome",
  wa_container(
    class = "wa-stack",
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_button(
      "example_button",
      "Click me",
      appearance = "filled",
      style = "width: 10rem;"
    ),
    wa_card("A simple card body")
  )
)

server <- function(input, output, session) {
}

shinyApp(ui, server)
```

You can use `shiny.webawesome` in two ways:

- use individual Web Awesome components inside an ordinary Shiny page
  such as [`fluidPage()`](https://rdrr.io/pkg/shiny/man/fluidPage.html)
- build the whole app page with
  [`webawesomePage()`](https://www.shiny-webawesome.org/reference/webawesomePage.md)

If you only need a few components inside an otherwise ordinary Shiny
app, using them inside
[`fluidPage()`](https://rdrr.io/pkg/shiny/man/fluidPage.html) is fine.
The package attaches its runtime dependencies automatically in that
case.

``` r
library(shiny)
library(shiny.webawesome)

ui <- fluidPage(
  h2("Mixed app"),
  wa_card(
    wa_badge("Beta", appearance = "filled"),
    "This app uses a few Web Awesome components inside fluidPage()."
  )
)

server <- function(input, output, session) {}

shinyApp(ui, server)
```

If Web Awesome is the main UI system for the app, prefer
[`webawesomePage()`](https://www.shiny-webawesome.org/reference/webawesomePage.md).
It attaches the package dependency once at page level and gives you a
cleaner full-page Web Awesome setup.

When you mix Web Awesome components into
[`fluidPage()`](https://rdrr.io/pkg/shiny/man/fluidPage.html) or another
Bootstrap layout, check the result in the browser. The components will
work, but your app may still need light CSS review for spacing,
typography, or theme/style mismatches between Bootstrap and Web Awesome.

## Documentation

- Package website: <https://www.shiny-webawesome.org>
- Source repository: <https://github.com/mbanand/shiny.webawesome>
- Bug reports: <https://github.com/mbanand/shiny.webawesome/issues>
- Package help pages: use `?topic` in R, for example
  [`?wa_button`](https://www.shiny-webawesome.org/reference/wa_button.md)
- Long-form package docs: installed vignettes and website articles

## Contributing

Feedback from package users is welcome, both on the package API and on
improvements to documentation for accuracy, clarity, or ease of
learning.

Contributions are also welcome, especially from front-end developers and
Web Awesome users who can help improve package ergonomics, examples, and
API coverage.

Please see the repository’s `CONTRIBUTING.md` file for contributing
guidance.

Repository project and workflow documentation is in the repo’s
`projectdocs/` directory.

## Coding Agents

For package users, the published
[`llms.txt`](https://www.shiny-webawesome.org/llms.txt) file provides a
machine-readable overview of the package API for coding agents and other
LLM-based tools.

For repository development guidance, including coding-agent workflow and
repo rules, see the repository’s `CONTRIBUTING.md` file.

# Package index

## Package Overview

Entry points for package-level orientation.

- [`shiny.webawesome`](https://www.shiny-webawesome.org/reference/shiny.webawesome-package.md)
  [`shiny.webawesome-package`](https://www.shiny-webawesome.org/reference/shiny.webawesome-package.md)
  : shiny.webawesome: Shiny Bindings for Web Awesome Components
- [`wa_version()`](https://www.shiny-webawesome.org/reference/wa_version.md)
  : Return the bundled Web Awesome version

## Layout and Page Helpers

Helpers for page scaffolding and layout convenience.

- [`wa_container()`](https://www.shiny-webawesome.org/reference/wa_container.md)
  : Construct a shiny.webawesome container
- [`webawesomePage()`](https://www.shiny-webawesome.org/reference/webawesomePage.md)
  : Construct a shiny.webawesome page

## Include and Icon Helpers

Helpers for browser-side includes and icon components.

- [`wa_icon()`](https://www.shiny-webawesome.org/reference/wa_icon.md) :

  Create a `wa-icon` component

- [`wa_include()`](https://www.shiny-webawesome.org/reference/wa_include.md)
  :

  Create a `wa-include` component

## Shiny Command Layer

Server-to-browser helpers and app-local JavaScript glue.

- [`wa_call_method()`](https://www.shiny-webawesome.org/reference/wa_call_method.md)
  : Call one browser-side method on a target element
- [`wa_js()`](https://www.shiny-webawesome.org/reference/wa_js.md) :
  Register a small JavaScript snippet with the page
- [`wa_set_property()`](https://www.shiny-webawesome.org/reference/wa_set_property.md)
  : Set one live property on a browser-side element

## Shiny Update Helpers

Curated update helpers for supported interactive components.

- [`wa_input()`](https://www.shiny-webawesome.org/reference/wa_input.md)
  [`update_wa_input()`](https://www.shiny-webawesome.org/reference/wa_input.md)
  :

  Create a `wa-input` component

- [`wa_number_input()`](https://www.shiny-webawesome.org/reference/wa_number_input.md)
  [`update_wa_number_input()`](https://www.shiny-webawesome.org/reference/wa_number_input.md)
  :

  Create a `wa-number-input` component

- [`wa_select()`](https://www.shiny-webawesome.org/reference/wa_select.md)
  [`update_wa_select()`](https://www.shiny-webawesome.org/reference/wa_select.md)
  :

  Create a `wa-select` component

- [`wa_slider()`](https://www.shiny-webawesome.org/reference/wa_slider.md)
  [`update_wa_slider()`](https://www.shiny-webawesome.org/reference/wa_slider.md)
  :

  Create a `wa-slider` component

- [`wa_textarea()`](https://www.shiny-webawesome.org/reference/wa_textarea.md)
  [`update_wa_textarea()`](https://www.shiny-webawesome.org/reference/wa_textarea.md)
  :

  Create a `wa-textarea` component

## Formatting Helpers

Helpers for browser-side format components.

- [`wa_format_bytes()`](https://www.shiny-webawesome.org/reference/wa_format_bytes.md)
  :

  Create a `wa-format-bytes` component

- [`wa_format_date()`](https://www.shiny-webawesome.org/reference/wa_format_date.md)
  :

  Create a `wa-format-date` component

- [`wa_format_number()`](https://www.shiny-webawesome.org/reference/wa_format_number.md)
  :

  Create a `wa-format-number` component

- [`wa_relative_time()`](https://www.shiny-webawesome.org/reference/wa_relative_time.md)
  :

  Create a `wa-relative-time` component

## Observer Utilities

Browser observer wrappers for intersection, mutation, and resize.

- [`wa_intersection_observer()`](https://www.shiny-webawesome.org/reference/wa_intersection_observer.md)
  :

  Create a `wa-intersection-observer` component

- [`wa_mutation_observer()`](https://www.shiny-webawesome.org/reference/wa_mutation_observer.md)
  :

  Create a `wa-mutation-observer` component

- [`wa_resize_observer()`](https://www.shiny-webawesome.org/reference/wa_resize_observer.md)
  :

  Create a `wa-resize-observer` component

## Components

Generated Web Awesome component wrappers.

- [`wa_animated_image()`](https://www.shiny-webawesome.org/reference/wa_animated_image.md)
  :

  Create a `wa-animated-image` component

- [`wa_animation()`](https://www.shiny-webawesome.org/reference/wa_animation.md)
  :

  Create a `wa-animation` component

- [`wa_avatar()`](https://www.shiny-webawesome.org/reference/wa_avatar.md)
  :

  Create a `wa-avatar` component

- [`wa_badge()`](https://www.shiny-webawesome.org/reference/wa_badge.md)
  :

  Create a `wa-badge` component

- [`wa_breadcrumb()`](https://www.shiny-webawesome.org/reference/wa_breadcrumb.md)
  :

  Create a `wa-breadcrumb` component

- [`wa_breadcrumb_item()`](https://www.shiny-webawesome.org/reference/wa_breadcrumb_item.md)
  :

  Create a `wa-breadcrumb-item` component

- [`wa_button()`](https://www.shiny-webawesome.org/reference/wa_button.md)
  :

  Create a `wa-button` component

- [`wa_button_group()`](https://www.shiny-webawesome.org/reference/wa_button_group.md)
  :

  Create a `wa-button-group` component

- [`wa_callout()`](https://www.shiny-webawesome.org/reference/wa_callout.md)
  :

  Create a `wa-callout` component

- [`wa_card()`](https://www.shiny-webawesome.org/reference/wa_card.md) :

  Create a `wa-card` component

- [`wa_carousel()`](https://www.shiny-webawesome.org/reference/wa_carousel.md)
  :

  Create a `wa-carousel` component

- [`wa_carousel_item()`](https://www.shiny-webawesome.org/reference/wa_carousel_item.md)
  :

  Create a `wa-carousel-item` component

- [`wa_checkbox()`](https://www.shiny-webawesome.org/reference/wa_checkbox.md)
  :

  Create a `wa-checkbox` component

- [`wa_color_picker()`](https://www.shiny-webawesome.org/reference/wa_color_picker.md)
  :

  Create a `wa-color-picker` component

- [`wa_comparison()`](https://www.shiny-webawesome.org/reference/wa_comparison.md)
  :

  Create a `wa-comparison` component

- [`wa_copy_button()`](https://www.shiny-webawesome.org/reference/wa_copy_button.md)
  :

  Create a `wa-copy-button` component

- [`wa_details()`](https://www.shiny-webawesome.org/reference/wa_details.md)
  :

  Create a `wa-details` component

- [`wa_dialog()`](https://www.shiny-webawesome.org/reference/wa_dialog.md)
  :

  Create a `wa-dialog` component

- [`wa_divider()`](https://www.shiny-webawesome.org/reference/wa_divider.md)
  :

  Create a `wa-divider` component

- [`wa_drawer()`](https://www.shiny-webawesome.org/reference/wa_drawer.md)
  :

  Create a `wa-drawer` component

- [`wa_dropdown()`](https://www.shiny-webawesome.org/reference/wa_dropdown.md)
  :

  Create a `wa-dropdown` component

- [`wa_dropdown_item()`](https://www.shiny-webawesome.org/reference/wa_dropdown_item.md)
  :

  Create a `wa-dropdown-item` component

- [`wa_input()`](https://www.shiny-webawesome.org/reference/wa_input.md)
  [`update_wa_input()`](https://www.shiny-webawesome.org/reference/wa_input.md)
  :

  Create a `wa-input` component

- [`wa_markdown()`](https://www.shiny-webawesome.org/reference/wa_markdown.md)
  :

  Create a `wa-markdown` component

- [`wa_number_input()`](https://www.shiny-webawesome.org/reference/wa_number_input.md)
  [`update_wa_number_input()`](https://www.shiny-webawesome.org/reference/wa_number_input.md)
  :

  Create a `wa-number-input` component

- [`wa_option()`](https://www.shiny-webawesome.org/reference/wa_option.md)
  :

  Create a `wa-option` component

- [`wa_page()`](https://www.shiny-webawesome.org/reference/wa_page.md) :

  Create a `wa-page` component

- [`wa_popover()`](https://www.shiny-webawesome.org/reference/wa_popover.md)
  :

  Create a `wa-popover` component

- [`wa_popup()`](https://www.shiny-webawesome.org/reference/wa_popup.md)
  :

  Create a `wa-popup` component

- [`wa_progress_bar()`](https://www.shiny-webawesome.org/reference/wa_progress_bar.md)
  :

  Create a `wa-progress-bar` component

- [`wa_progress_ring()`](https://www.shiny-webawesome.org/reference/wa_progress_ring.md)
  :

  Create a `wa-progress-ring` component

- [`wa_qr_code()`](https://www.shiny-webawesome.org/reference/wa_qr_code.md)
  :

  Create a `wa-qr-code` component

- [`wa_radio()`](https://www.shiny-webawesome.org/reference/wa_radio.md)
  :

  Create a `wa-radio` component

- [`wa_radio_group()`](https://www.shiny-webawesome.org/reference/wa_radio_group.md)
  :

  Create a `wa-radio-group` component

- [`wa_rating()`](https://www.shiny-webawesome.org/reference/wa_rating.md)
  :

  Create a `wa-rating` component

- [`wa_scroller()`](https://www.shiny-webawesome.org/reference/wa_scroller.md)
  :

  Create a `wa-scroller` component

- [`wa_select()`](https://www.shiny-webawesome.org/reference/wa_select.md)
  [`update_wa_select()`](https://www.shiny-webawesome.org/reference/wa_select.md)
  :

  Create a `wa-select` component

- [`wa_skeleton()`](https://www.shiny-webawesome.org/reference/wa_skeleton.md)
  :

  Create a `wa-skeleton` component

- [`wa_slider()`](https://www.shiny-webawesome.org/reference/wa_slider.md)
  [`update_wa_slider()`](https://www.shiny-webawesome.org/reference/wa_slider.md)
  :

  Create a `wa-slider` component

- [`wa_spinner()`](https://www.shiny-webawesome.org/reference/wa_spinner.md)
  :

  Create a `wa-spinner` component

- [`wa_split_panel()`](https://www.shiny-webawesome.org/reference/wa_split_panel.md)
  :

  Create a `wa-split-panel` component

- [`wa_switch()`](https://www.shiny-webawesome.org/reference/wa_switch.md)
  :

  Create a `wa-switch` component

- [`wa_tab()`](https://www.shiny-webawesome.org/reference/wa_tab.md) :

  Create a `wa-tab` component

- [`wa_tab_group()`](https://www.shiny-webawesome.org/reference/wa_tab_group.md)
  :

  Create a `wa-tab-group` component

- [`wa_tab_panel()`](https://www.shiny-webawesome.org/reference/wa_tab_panel.md)
  :

  Create a `wa-tab-panel` component

- [`wa_tag()`](https://www.shiny-webawesome.org/reference/wa_tag.md) :

  Create a `wa-tag` component

- [`wa_textarea()`](https://www.shiny-webawesome.org/reference/wa_textarea.md)
  [`update_wa_textarea()`](https://www.shiny-webawesome.org/reference/wa_textarea.md)
  :

  Create a `wa-textarea` component

- [`wa_tooltip()`](https://www.shiny-webawesome.org/reference/wa_tooltip.md)
  :

  Create a `wa-tooltip` component

- [`wa_tree()`](https://www.shiny-webawesome.org/reference/wa_tree.md) :

  Create a `wa-tree` component

- [`wa_tree_item()`](https://www.shiny-webawesome.org/reference/wa_tree_item.md)
  :

  Create a `wa-tree-item` component

- [`wa_zoomable_frame()`](https://www.shiny-webawesome.org/reference/wa_zoomable_frame.md)
  :

  Create a `wa-zoomable-frame` component

# Articles

### Getting Started

- [Getting Started with
  shiny.webawesome](https://www.shiny-webawesome.org/articles/get-started.md):

### User Articles

- [Layout
  Utilities](https://www.shiny-webawesome.org/articles/layout-utilities.md):
- [Styling and
  Theming](https://www.shiny-webawesome.org/articles/styling-and-theming.md):
- [Shiny
  Bindings](https://www.shiny-webawesome.org/articles/shiny-bindings.md):
- [Extra Attributes via
  htmltools](https://www.shiny-webawesome.org/articles/htmltools-attributes.md):
- [Command
  API](https://www.shiny-webawesome.org/articles/command-api.md):
- [Package
  Options](https://www.shiny-webawesome.org/articles/package-options.md):
- [Examples](https://www.shiny-webawesome.org/articles/examples.md):

### Maintainer Articles

- [Build
  Tools](https://www.shiny-webawesome.org/articles/build-tools.md):