express.ui.Theme

express.ui.Theme(self, preset=None, name=None, include_paths=None)

Create a custom Shiny theme.

The Theme class allows you to create a custom Shiny theme by providing custom Sass code. The theme can be based on one of the available presets, such as "shiny" or "bootstrap", or a Bootswatch theme. Use the .add_*() methods can be chained together to add custom Sass functions, defaults, mixins, and rules.

Pass the Theme object directly to the theme argument of any Shiny page function, such as page_sidebar or page_navbar. In Shiny Express apps, use the theme argument of page_opts to set the app theme.

Note: Compiling custom themes requires the libsass package, which is not installed by default with Shiny. Use pip install libsass or pip install "shiny[theme]" to install it.

Customized themes are compiled to CSS when the theme is used. The Theme class caches the compiled CSS so that it's only compiled for the first user to load your app, but you can speed up app loading (and avoid the runtime libsass dependency) by pre-compiling the theme CSS and saving it to a file. To do this, use the .to_css() method to render the theme to a single minified CSS string.

my_theme.py

from pathlib import Path

from shiny import ui

my_theme = (
    ui.Theme("shiny")
    .add_defaults(
        my_purple="#aa00aa",
    )
    .add_mixins(
        headings_color="$my-purple",
    )
)

with open(Path(__file__).parent / "my_theme.css", "w") as f:
    f.write(my_theme.to_css())

Run this script with python my_theme.py to generate the CSS file. Once saved to a file, the CSS can be used in any Shiny app by passing the file path to the theme argument instead of the Theme object.

app.py

from pathlib import Path

from shiny import App, ui

app_ui = ui.page_fluid(
    ui.h2("Hello, themed Shiny!"),
    # App content here
    title="My App",
    theme=Path(__file__).parent / "my_theme.css",
)

def server(input):
    pass

app = App(app_ui, server)

Parameters

preset : str | None = None

The name of the preset to use as a base. "shiny" is the default theme for Shiny apps and "bootstrap" uses standard Bootstrap 5 styling. Bootswatch theme presets are also available. Use Theme.available_presets() to see the full list.

name : Optional[str] = None

A custom name for the theme. If not provided, the preset name will be used.

include_paths : Optional[str | pathlib.Path | list[str | pathlib.Path]] = None

Additional paths to include when looking for Sass files used in @import statements in the theme. This can be a single path as a string or pathlib.Path, or a list of paths. The paths should point to directories containing additional Sass files that the theme depends on.

Raises

: ValueError

If the preset is not a valid theme preset.

Methods

Name	Description
add_defaults	Add custom default values to the theme.
add_functions	Add custom Sass functions to the theme.
add_mixins	Add custom Sass mixins to the theme.
add_rules	Add custom Sass rules to the theme.
available_presets	Get a list of available theme presets.
from_brand	Create a custom Shiny theme from a _brand.yml
to_css	Compile the theme to CSS and return the result as a string.
to_sass	Returns the custom theme as a single Sass string.

add_defaults

express.ui.Theme.add_defaults(*args, **kwargs)

Add custom default values to the theme.

Sass code added via this method will be placed before the default values of the theme preset, allowing you to override or extend the default values.

Parameters

*args : str = ()

Sass code, as a single or multiple strings, containing default value declarations to add.

****kwargs** : str | float | int | bool | None = {}

Keyword arguments containing default value declarations to add. The keys should be Sass variable names using underscore casing that will be transformed automatically to kebab-case. For example, .add_defaults(primary_color="#ff0000") is equivalent to .add_defaults("$primary-color: #ff0000 !default;").

add_functions

express.ui.Theme.add_functions(*args)

Add custom Sass functions to the theme.

Sass code added via this method will be placed after the function declarations from the theme preset, allowing you to override or extend the default functions.

Parameters

*args : str = ()

The Sass functions to add as a single or multiple strings.

add_mixins

express.ui.Theme.add_mixins(*args, **kwargs)

Add custom Sass mixins to the theme.

Sass code added via this method will be placed after the mixin declarations from the theme preset, allowing you to override or extend the default mixins.

Parameters

*args : str = ()

Sass code, as a single or multiple strings, containing mixins to add.

****kwargs** : str | float | int | bool | None = {}

Keyword arguments containing Sass value declarations to add. The keys should be Sass variable names using underscore casing that will be transformed automatically to kebab-case. For example, .add_mixins(primary_color="#ff0000") is equivalent to .add_mixins("$primary-color: #ff0000;").

add_rules

express.ui.Theme.add_rules(*args, **kwargs)

Add custom Sass rules to the theme.

Sass code added via this method will be placed after the rule declarations from the theme preset, allowing you to override or extend the default rules.

Parameters

*args : str = ()

Sass code, as a single or multiple strings, containing rules to add.

****kwargs** : str | float | int | bool | None = {}

Keyword arguments containing Sass value declarations to add. The keys should be Sass variable names using underscore casing that will be transformed automatically to kebab-case. For example, .add_rules(primary_color="#ff0000") is equivalent to .add_rules("$primary-color: #ff0000;").

available_presets

express.ui.Theme.available_presets()

Get a list of available theme presets.

from_brand

express.ui.Theme.from_brand(brand)

Create a custom Shiny theme from a _brand.yml

Creates a custom Shiny theme for your brand using brand.yml, a single YAML file that describes the brand's color and typography. Learn more about writing a _brand.yml file for your brand at the brand.yml homepage.

As a simple example, suppose your brand guidelines include a color palette with custom orange and black colors. The orange is used as the primary accent color and the black for all text. For typography, the brand also uses Roboto and Roboto Mono from Google Fonts for text and monospace-styled text, respectively. Here's a _brand.yml file for this brand:

_brand.yml

meta:
  name: brand.yml Example

color:
  palette:
    orange: "#F96302"
    black: "#000000"
  foreground: black
  primary: orange

typography:
  fonts:
    - family: Roboto
      source: google
    - family: Roboto Mono
      source: google
  base: Roboto
  monospace: Roboto Mono

You can store the _brand.yml file next to your Shiny app.py or, for larger projects, in a parent folder. To use a theme generated from the _brand.yml file, call from_brand on __file__ and pass the result to the theme argument of page_opts (Shiny Express) or the theme argument of shiny.express.ui.page_* functions, like page_sidebar.

app.py

from shiny.express import input, render, ui

ui.page_opts(theme=ui.Theme.from_brand(__file__))

ui.input_slider("n", "N", 0, 100, 20)


@render.code
def txt():
    return f"n*2 is {input.n() * 2}"

Parameters

brand : ‘str | pathlib.Path | Brand’

A brand_yml.Brand instance, or a path to help locate _brand.yml. For a path, you can pass __file__ or a directory containing the _brand.yml or a path directly to the _brand.yml file.

Returns

:

A shiny.express.ui.Theme instance with a custom Shiny theme created from the brand guidelines (see brand_yml.Brand).

to_css

express.ui.Theme.to_css(compile_args=None)

Compile the theme to CSS and return the result as a string.

Parameters

compile_args : Optional[SassCompileArgs] = None

A dictionary of keyword arguments to pass to sass.compile().

Returns

: str

The compiled CSS for the theme. The value is cached such that previously compiled themes are returned immediately. Adding additional custom Sass code or changing the preset will invalidate the cache.

to_sass

express.ui.Theme.to_sass()

Returns the custom theme as a single Sass string.

Returns

: str

The custom theme as a single Sass string.