express.ui.Theme
express.ui.Theme(self, preset='shiny', 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 "shiny")
ui.Theme(
.add_defaults(="#aa00aa",
my_purple
)
.add_mixins(="$my-purple",
headings_color
)
)
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
= ui.page_fluid(
app_ui "Hello, themed Shiny!"),
ui.h2(# App content here
="My App",
title=Path(__file__).parent / "my_theme.css",
theme
)
def server(input):
pass
= App(app_ui, server) app
Parameters
preset:
ShinyThemePreset
= ‘shiny’-
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. UseTheme.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
Type | Description |
---|---|
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. |
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.
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
Type | Description |
---|---|
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
Type | Description |
---|---|
str | The custom theme as a single Sass string. |