# Calcite Design System for R

The [calcite](https://r.esri.com/calcite/) package provides R bindings
to Esri’s [Calcite Design
System](https://developers.arcgis.com/calcite-design-system/), designed
to work directly with Shiny or standalone HTML.

> \[!TIP\]
>
> An [`llms.txt`](https://r.esri.com/calcite/llms.txt) file is available
> to provide context for LLMs when working with this package.

## Installation

The [calcite](https://r.esri.com/calcite/) package is available on
GitHub. Install it using the following command:

``` r
remotes::install_github("r-arcgis/calcite")
```

## Usage

[calcite](https://r.esri.com/calcite/) consists of many components. See
them all in the [official
documentation](https://developers.arcgis.com/calcite-design-system/components/).

Use the calcite components to scaffold the UI of your Shiny application.
The example below uses
[`calcite_panel()`](https://r.esri.com/calcite/reference/calcite_panel.md),
[`calcite_block()`](https://r.esri.com/calcite/reference/calcite_block.md),
and
[`calcite_select()`](https://r.esri.com/calcite/reference/calcite_select.md)
to build a sidebar-driven scatter plot explorer with the
`palmerpenguins` dataset:

``` r
library(calcite)

open_example("page-sidebar-penguins")
```

Use
[`list_examples()`](https://r.esri.com/calcite/reference/examples.md) to
see all included examples,
[`run_example()`](https://r.esri.com/calcite/reference/examples.md) to
run one directly, or
[`open_example()`](https://r.esri.com/calcite/reference/examples.md) to
browse and open one:

``` r
open_example()
```

## App Layouts

[calcite](https://r.esri.com/calcite/) provides layout functions that
make it easy to structure Shiny apps with sidebars, navigation headers,
and main content areas.

### `page_sidebar()`

The simplest way to build a standard Calcite app layout — a sidebar on
the left and a main content area on the right, optionally with a
navigation header. For a full working example, try
`open_example("page-sidebar-penguins")`.

``` r
library(shiny)
library(calcite)

ui <- page_sidebar(
  title = "My App",
  sidebar = calcite_panel(
    heading = "Controls",
    calcite_block(
      heading = "Options",
      collapsible = TRUE,
      expanded = TRUE,
      calcite_checkbox(id = "show_labels", label_text = "Show labels")
    )
  ),
  calcite_panel(heading = "Map View")
)

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

shinyApp(ui, server)
```

### `page_actionbar()`

For map-style apps with an action bar that toggles panels. See
`open_example("page-actionbar")` for a runnable example:

``` r
ui <- page_actionbar(
  title = "Wildlife Areas",
  actions = calcite_action_bar(
    id = "my_bar",
    calcite_action(text = "Layers", icon = "layers", active = TRUE),
    calcite_action(text = "Legend", icon = "legend")
  ),
  panel_content = list(
    calcite_panel(
      id = "layers_panel",
      heading = "Layers",
      calcite_block(heading = "Options", collapsible = TRUE, expanded = TRUE)
    ),
    calcite_panel(
      id = "legend_panel",
      heading = "Legend",
      hidden = TRUE,
      calcite_block(heading = "Legend items", collapsible = TRUE, expanded = TRUE)
    )
  ),
  calcite_panel(heading = "Map View")
)

server <- function(input, output, session) {
  observeEvent(input$my_bar, {
    update_calcite("layers_panel", hidden = input$my_bar != "Layers")
    update_calcite("legend_panel", hidden = input$my_bar != "Legend")
  }, ignoreInit = TRUE)
}

shinyApp(ui, server)
```

## Using Component Properties

Component properties are accessible via `input$id` in a Shiny `server`
function, with each property available as a named list element:

``` r
library(shiny)
library(calcite)

ui <- calcite_shell(
  calcite_block(
    id = "effects_block",
    heading = "Layer effects",
    description = "Adjust blur, highlight, and more",
    collapsible = TRUE,
    expanded = TRUE,
    icon_start = "effects",
    calcite_label(
      "Effect intensity",
      calcite_slider(
        id = "intensity",
        value = 50,
        min = 0,
        max = 100,
        step = 5,
        label_handles = TRUE
      )
    )
  )
)

server <- function(input, output, session) {
  observeEvent(input$intensity, {
    cat(str(input$intensity))
    cat(sprintf("Slider value: %s\n", input$intensity$value))
  })
}

shiny::shinyApp(ui, server)
#> Slider value: 45
#> List of 11
#>  $ value       : int 45
#>  $ min         : int 0
#>  $ max         : int 100
#>  $ step        : int 5
#>  $ disabled    : logi FALSE
#>  $ histogram   : NULL
#>  $ labelHandles: logi TRUE
#>  $ labelTicks  : logi FALSE
#>  $ scale       : chr "m"
#>  $ precise     : logi FALSE
#>  $ snap        : logi FALSE
```

## Shiny Reactivity

Properties can be updated from the server using
[`update_calcite()`](https://r.esri.com/calcite/reference/update_calcite.md),
which takes the `id` of the component and named property values:

``` r
library(calcite)
library(shiny)

ui <- calcite_shell(
  calcite_panel(
    heading = "Demo",
    calcite_button(id = "show_notice", "Show notice"),
    calcite_notice(
      id = "my_notice",
      open = FALSE,
      closable = TRUE,
      kind = "success",
      icon = TRUE,
      title = "Nice!",
      message = "Your changes have been saved."
    )
  )
)

server <- function(input, output, session) {
  observeEvent(input$show_notice$clicks, {
    update_calcite("my_notice", open = TRUE)
  })
}

shiny::shinyApp(ui, server)
```

### Building custom layouts with `calcite_shell()`

For full control, use
[`calcite_shell()`](https://r.esri.com/calcite/reference/calcite_shell.md)
directly. Place a
[`calcite_shell_panel()`](https://r.esri.com/calcite/reference/calcite_shell_panel.md)
in `panel_start` or `panel_end`, wrapping a
[`calcite_panel()`](https://r.esri.com/calcite/reference/calcite_panel.md)
with
[`calcite_block()`](https://r.esri.com/calcite/reference/calcite_block.md)
components inside:

``` r
ui <- calcite_shell(
  panel_start = calcite_shell_panel(
    width = "m",
    calcite_panel(
      heading = "Layers",
      calcite_block(
        heading = "Basemap",
        collapsible = TRUE,
        expanded = TRUE
      )
    )
  ),
  calcite_panel(heading = "Map View")
)

shinyApp(ui, server)
```

The layout hierarchy is:

``` R
calcite_shell()
  panel_start = calcite_shell_panel()   # controls width, display mode
    calcite_panel()                     # header, footer, actions
      calcite_block()                   # collapsible sections
        # your controls here
  calcite_panel()                       # main content area
```

## Additional Components

Many additional components are available but do not yet have explicitly
named parameters. They accept attributes via `...` using kebab-case
names, for example `` `icon-start` = "layers" ``. This is actively being
worked on. See the full list at
[r.esri.com/calcite/reference/index.html#generated-components](https://r.esri.com/calcite/reference/index.html#generated-components).

# Package index

## Layout & Structure

Components for organizing and structuring application layouts.

- [`calcite_shell()`](https://r.esri.com/calcite/reference/calcite_shell.md)
  : Create a Calcite Shell Layout
- [`calcite_shell_panel()`](https://r.esri.com/calcite/reference/calcite_shell_panel.md)
  : Create a Calcite Shell Panel Component
- [`calcite_shell_center_row()`](https://r.esri.com/calcite/reference/calcite_shell_center_row.md)
  : Create a ShellCenterRow component
- [`calcite_panel()`](https://r.esri.com/calcite/reference/calcite_panel.md)
  : Create a Calcite Panel Component
- [`calcite_accordion()`](https://r.esri.com/calcite/reference/calcite_accordion.md)
  : Create a Calcite Accordion Component
- [`calcite_accordion_item()`](https://r.esri.com/calcite/reference/calcite_accordion_item.md)
  : Create a Calcite Accordion Item Component
- [`calcite_block()`](https://r.esri.com/calcite/reference/calcite_block.md)
  : Create a Calcite Block Component
- [`calcite_block_section()`](https://r.esri.com/calcite/reference/calcite_block_section.md)
  : Create a BlockSection component
- [`calcite_tile()`](https://r.esri.com/calcite/reference/calcite_tile.md)
  : Create a Calcite Tile Component
- [`calcite_tile_group()`](https://r.esri.com/calcite/reference/calcite_tile_group.md)
  : Create a Calcite Tile Group Component

## Forms & Inputs

Input components for collecting user data and form interactions.

- [`calcite_label()`](https://r.esri.com/calcite/reference/calcite_label.md)
  : Create a Calcite Label Component
- [`calcite_checkbox()`](https://r.esri.com/calcite/reference/calcite_checkbox.md)
  : Create a Calcite Checkbox Component
- [`calcite_input_text()`](https://r.esri.com/calcite/reference/calcite_input_text.md)
  : Create a Calcite Input Text Component
- [`calcite_input_number()`](https://r.esri.com/calcite/reference/calcite_input_number.md)
  : Create a Calcite Input Number Component
- [`calcite_input_message()`](https://r.esri.com/calcite/reference/calcite_input_message.md)
  : Create a Calcite Input Message Component
- [`calcite_input_file()`](https://r.esri.com/calcite/reference/calcite_input_file.md)
  : Create a Calcite File Input Component
- [`calcite_slider()`](https://r.esri.com/calcite/reference/calcite_slider.md)
  : Create a Calcite Slider Component
- [`calcite_switch()`](https://r.esri.com/calcite/reference/calcite_switch.md)
  : Create a Calcite Switch Component
- [`calcite_select()`](https://r.esri.com/calcite/reference/calcite_select.md)
  : Create a Calcite Select Component
- [`calcite_option()`](https://r.esri.com/calcite/reference/calcite_option.md)
  : Create a Calcite Option Component
- [`calcite_date_picker()`](https://r.esri.com/calcite/reference/calcite_date_picker.md)
  : Create a Calcite Date Picker Component
- [`calcite_segmented_control()`](https://r.esri.com/calcite/reference/calcite_segmented_control.md)
  : Create a Calcite Segmented Control Component
- [`calcite_segmented_control_item()`](https://r.esri.com/calcite/reference/calcite_segmented_control_item.md)
  : Create a Calcite Segmented Control Item Component

## Actions & Buttons

Interactive components for triggering actions and navigation.

- [`calcite_button()`](https://r.esri.com/calcite/reference/calcite_button.md)
  : Create a Calcite Button Component
- [`calcite_link()`](https://r.esri.com/calcite/reference/calcite_link.md)
  : Create a Calcite Link Component
- [`calcite_action()`](https://r.esri.com/calcite/reference/calcite_action.md)
  : Create a Calcite Action Component
- [`calcite_action_group()`](https://r.esri.com/calcite/reference/calcite_action_group.md)
  : Create a Calcite Action Group Component
- [`calcite_action_bar()`](https://r.esri.com/calcite/reference/calcite_action_bar.md)
  : Create a Calcite Action Bar Component

## Data Display

Components for displaying tabular data.

- [`calcite_table()`](https://r.esri.com/calcite/reference/calcite_table.md)
  : Create a Calcite Table Component
- [`calcite_table_header()`](https://r.esri.com/calcite/reference/calcite_table_header.md)
  : Create a Calcite Table Header

## Feedback & Messaging

Components for displaying messages, alerts, and user feedback.

- [`calcite_alert()`](https://r.esri.com/calcite/reference/calcite_alert.md)
  [`calcite_alert_brand()`](https://r.esri.com/calcite/reference/calcite_alert.md)
  [`calcite_alert_danger()`](https://r.esri.com/calcite/reference/calcite_alert.md)
  [`calcite_alert_info()`](https://r.esri.com/calcite/reference/calcite_alert.md)
  [`calcite_alert_success()`](https://r.esri.com/calcite/reference/calcite_alert.md)
  [`calcite_alert_warning()`](https://r.esri.com/calcite/reference/calcite_alert.md)
  : Create a Calcite Alert Component
- [`calcite_notice()`](https://r.esri.com/calcite/reference/calcite_notice.md)
  : Create a Calcite Notice Component
- [`calcite_scrim()`](https://r.esri.com/calcite/reference/calcite_scrim.md)
  : Create a Calcite Scrim Component

## Page Templates

Pre-built page layouts for common application patterns.

- [`page_actionbar()`](https://r.esri.com/calcite/reference/page_actionbar.md)
  : Create a Shell with Action Bar Layout
- [`page_navbar()`](https://r.esri.com/calcite/reference/page_navbar.md)
  : Create a Shell with Navigation Bar Layout
- [`page_sidebar()`](https://r.esri.com/calcite/reference/page_sidebar.md)
  : Create a Shell with Sidebar Panel Layout

## Utilities

Helper functions for package management and configuration.

- [`calcite_version()`](https://r.esri.com/calcite/reference/calcite_version.md)
  : Calcite components version
- [`update_calcite()`](https://r.esri.com/calcite/reference/update_calcite.md)
  : Update Calcite Component Properties
- [`list_examples()`](https://r.esri.com/calcite/reference/examples.md)
  [`run_example()`](https://r.esri.com/calcite/reference/examples.md)
  [`open_example()`](https://r.esri.com/calcite/reference/examples.md) :
  Calcite examples

## Generated Components

Auto-generated component bindings. These are fully functional but may
have less detailed documentation than manually created components above.

- [`calcite_action_pad()`](https://r.esri.com/calcite/reference/calcite_action_pad.md)
  : Create a ActionPad component
- [`calcite_avatar()`](https://r.esri.com/calcite/reference/calcite_avatar.md)
  : Create a Avatar component
- [`calcite_card()`](https://r.esri.com/calcite/reference/calcite_card.md)
  : Create a Card component
- [`calcite_card_group()`](https://r.esri.com/calcite/reference/calcite_card_group.md)
  : Create a CardGroup component
- [`calcite_carousel()`](https://r.esri.com/calcite/reference/calcite_carousel.md)
  : Create a Carousel component
- [`calcite_carousel_item()`](https://r.esri.com/calcite/reference/calcite_carousel_item.md)
  : Create a CarouselItem component
- [`calcite_chip()`](https://r.esri.com/calcite/reference/calcite_chip.md)
  : Create a Chip component
- [`calcite_chip_group()`](https://r.esri.com/calcite/reference/calcite_chip_group.md)
  : Create a ChipGroup component
- [`calcite_color_picker()`](https://r.esri.com/calcite/reference/calcite_color_picker.md)
  : Create a ColorPicker component
- [`calcite_combobox()`](https://r.esri.com/calcite/reference/calcite_combobox.md)
  : Create a Combobox component
- [`calcite_combobox_item()`](https://r.esri.com/calcite/reference/calcite_combobox_item.md)
  : Create a ComboboxItem component
- [`calcite_combobox_item_group()`](https://r.esri.com/calcite/reference/calcite_combobox_item_group.md)
  : Create a ComboboxItemGroup component
- [`calcite_dialog()`](https://r.esri.com/calcite/reference/calcite_dialog.md)
  : Create a Dialog component
- [`calcite_dropdown()`](https://r.esri.com/calcite/reference/calcite_dropdown.md)
  : Create a Dropdown component
- [`calcite_dropdown_group()`](https://r.esri.com/calcite/reference/calcite_dropdown_group.md)
  : Create a DropdownGroup component
- [`calcite_dropdown_item()`](https://r.esri.com/calcite/reference/calcite_dropdown_item.md)
  : Create a DropdownItem component
- [`calcite_fab()`](https://r.esri.com/calcite/reference/calcite_fab.md)
  : Create a Fab component
- [`calcite_filter()`](https://r.esri.com/calcite/reference/calcite_filter.md)
  : Create a Filter component
- [`calcite_flow()`](https://r.esri.com/calcite/reference/calcite_flow.md)
  : Create a Flow component
- [`calcite_flow_item()`](https://r.esri.com/calcite/reference/calcite_flow_item.md)
  : Create a FlowItem component
- [`calcite_icon()`](https://r.esri.com/calcite/reference/calcite_icon.md)
  : Create a Icon component
- [`calcite_inline_editable()`](https://r.esri.com/calcite/reference/calcite_inline_editable.md)
  : Create a InlineEditable component
- [`calcite_input_date_picker()`](https://r.esri.com/calcite/reference/calcite_input_date_picker.md)
  : Create a InputDatePicker component
- [`calcite_input_time_picker()`](https://r.esri.com/calcite/reference/calcite_input_time_picker.md)
  : Create a InputTimePicker component
- [`calcite_input_time_zone()`](https://r.esri.com/calcite/reference/calcite_input_time_zone.md)
  : Create a InputTimeZone component
- [`calcite_list()`](https://r.esri.com/calcite/reference/calcite_list.md)
  : Create a List component
- [`calcite_list_item()`](https://r.esri.com/calcite/reference/calcite_list_item.md)
  : Create a ListItem component
- [`calcite_list_item_group()`](https://r.esri.com/calcite/reference/calcite_list_item_group.md)
  : Create a ListItemGroup component
- [`calcite_loader()`](https://r.esri.com/calcite/reference/calcite_loader.md)
  : Create a Loader component
- [`calcite_menu()`](https://r.esri.com/calcite/reference/calcite_menu.md)
  : Create a Menu component
- [`calcite_menu_item()`](https://r.esri.com/calcite/reference/calcite_menu_item.md)
  : Create a MenuItem component
- [`calcite_meter()`](https://r.esri.com/calcite/reference/calcite_meter.md)
  : Create a Meter component
- [`calcite_modal()`](https://r.esri.com/calcite/reference/calcite_modal.md)
  : Create a Modal component
- [`calcite_navigation()`](https://r.esri.com/calcite/reference/calcite_navigation.md)
  : Create a Navigation component
- [`calcite_navigation_logo()`](https://r.esri.com/calcite/reference/calcite_navigation_logo.md)
  : Create a NavigationLogo component
- [`calcite_navigation_user()`](https://r.esri.com/calcite/reference/calcite_navigation_user.md)
  : Create a NavigationUser component
- [`calcite_option_group()`](https://r.esri.com/calcite/reference/calcite_option_group.md)
  : Create a OptionGroup component
- [`calcite_pagination()`](https://r.esri.com/calcite/reference/calcite_pagination.md)
  : Create a Pagination component
- [`calcite_popover()`](https://r.esri.com/calcite/reference/calcite_popover.md)
  : Create a Popover component
- [`calcite_progress()`](https://r.esri.com/calcite/reference/calcite_progress.md)
  : Create a Progress component
- [`calcite_radio_button()`](https://r.esri.com/calcite/reference/calcite_radio_button.md)
  : Create a RadioButton component
- [`calcite_radio_button_group()`](https://r.esri.com/calcite/reference/calcite_radio_button_group.md)
  : Create a RadioButtonGroup component
- [`calcite_rating()`](https://r.esri.com/calcite/reference/calcite_rating.md)
  : Create a Rating component
- [`calcite_sheet()`](https://r.esri.com/calcite/reference/calcite_sheet.md)
  : Create a Sheet component
- [`calcite_shell_center_row()`](https://r.esri.com/calcite/reference/calcite_shell_center_row.md)
  : Create a ShellCenterRow component
- [`calcite_shell_panel()`](https://r.esri.com/calcite/reference/calcite_shell_panel.md)
  : Create a Calcite Shell Panel Component
- [`calcite_split_button()`](https://r.esri.com/calcite/reference/calcite_split_button.md)
  : Create a SplitButton component
- [`calcite_stepper()`](https://r.esri.com/calcite/reference/calcite_stepper.md)
  : Create a Stepper component
- [`calcite_stepper_item()`](https://r.esri.com/calcite/reference/calcite_stepper_item.md)
  : Create a StepperItem component
- [`calcite_tab()`](https://r.esri.com/calcite/reference/calcite_tab.md)
  : Create a Tab component
- [`calcite_tab_nav()`](https://r.esri.com/calcite/reference/calcite_tab_nav.md)
  : Create a TabNav component
- [`calcite_tab_title()`](https://r.esri.com/calcite/reference/calcite_tab_title.md)
  : Create a TabTitle component
- [`calcite_tabs()`](https://r.esri.com/calcite/reference/calcite_tabs.md)
  : Create a Tabs component
- [`calcite_text_area()`](https://r.esri.com/calcite/reference/calcite_text_area.md)
  : Create a TextArea component
- [`calcite_time_picker()`](https://r.esri.com/calcite/reference/calcite_time_picker.md)
  : Create a TimePicker component
- [`calcite_tip()`](https://r.esri.com/calcite/reference/calcite_tip.md)
  : Create a Tip component
- [`calcite_tip_group()`](https://r.esri.com/calcite/reference/calcite_tip_group.md)
  : Create a TipGroup component
- [`calcite_tip_manager()`](https://r.esri.com/calcite/reference/calcite_tip_manager.md)
  : Create a TipManager component
- [`calcite_tooltip()`](https://r.esri.com/calcite/reference/calcite_tooltip.md)
  : Create a Tooltip component
- [`calcite_tree()`](https://r.esri.com/calcite/reference/calcite_tree.md)
  : Create a Tree component
- [`calcite_tree_item()`](https://r.esri.com/calcite/reference/calcite_tree_item.md)
  : Create a TreeItem component