# SAL - Style and Layout for Streamlit
## What does it do?
This library lets you style Streamlit components with ease!
Here is a quick example of what it can do for you:
```sass
// You define SASS style using a predefined placeholder
%sal-button {
border: 1px dashed antiquewhite
}
// Or you define SASS style using a custom placeholder (*)
%btn-large {
padding: 12px 18px
p {
font-weight:bold
}
}
```
(*[Read more about custom placeholders](https://github.com/datarobot-oss/streamlit-sal/tree/main?tab=readme-ov-file#add-custom-classes-to-sal-components))
Run `streamlit-sal compile`
```python
import streamlit as st
import streamlit_sal as sal
from streamlit_sal import sal_stylesheet
with sal_stylesheet(move_sidebar_right=True):
# The Streamlit sidebar is now on the right side of the view!
# This wraps the 'btn-large' and general 'sal-button' styles onto the st.button in the context
with sal.button('btn-large'):
large_button = st.button('Big button')
# It won't affect other usages of st.button
normal_button = st.button('Streamlit button')
```
Result:
> **Disclaimer**
>
> We cannot guarantee that this library will continue to work for every Streamlit release!
## How to install it?
Install with `pip install streamlit-sal`
From the root of your Streamlit app run: `streamlit-sal init`
Fill in the config variables for the desired style source and destination path.
It will then create a `main.scss` in the given source path and a `.streamlit_sal` in the project root path
You can test whether the `init` was successful by running `streamlit-sal compile` which should create a CSS file.
## How to use it?
(*[Make sure to initiate the library first](https://github.com/datarobot-oss/streamlit-sal/tree/main?tab=readme-ov-file#how-to-install-it))
Wrap your app code with the stylesheet:
```python
from streamlit_sal import sal_stylesheet
with sal_stylesheet():
# Your app code goes here!
```
This will render a streamlit markdown element with a style tag containing the compiled CSS before your code
### Add placeholders, compile and render
Navigate to your `main.scss` and start adding the style placeholders that you need. The available predefined
placeholders can be found [here](https://github.com/datarobot/streamlit-sal/PLACEHOLDERS.md). A rule of thumb for
placeholders is that every Streamlit component name
exists with a `sal-` prefix and underscores are replaced by dashes (`st.download_button` -> `sal-download-button`)
Let's take an example for st.button. We add a new border style for the existing placeholder:
```sass
%sal-button {
border: 1px dashed red
}
```
Now we run `streamlit-sal compile` to create the CSS stylesheet sal-stylesheet.css (default name)
The CSS will now apply to all st.button elements that are wrapped with sal.button():
```python
import streamlit as st
import streamlit_sal as sal
from streamlit_sal import sal_stylesheet
with sal_stylesheet():
# This wraps the default 'sal-button' styles onto the st.button within the context
with sal.button():
st.button('Red Border Button')
```
### Add custom classes to SAL components
SAL can easily be extended with additional custom placeholders/classes. Though it is important to register the
new placeholders with the correct components.
```sass
// Define a custom placeholder (avoid sal- prefix to minimize risk of duplicates)
%btn-large {
padding: 12px 18px
p {
font-weight:bold
}
}
```
The above placeholder will not be compiled into the final CSS stylesheet yet. It first needs to be registered
to the sal-button. You can find the `$custom-classes` variable at the bottom of your `main.scss`:
```sass
$custom-classes: (
sal-button: (btn-large),
)
```
Multiple placeholders can be added to the same components and even reused between multiple components:
```sass
$custom-classes: (
sal-button: (btn-large, btn-primary),
sal-download-button: (btn-primary),
)
```
### Normal elements vs container elements
Most elements behave the same, but there are some container-type elements that need special treatment.
For these elements you will need to pass down the container to SAL to make it work:
- `with sal.column(..., container=col1): # From col0, col1 = st.columns(2)`
- `with sal.popover_content(..., container=container): # From container = st.container()`
SAL should warn you when a container element was not used correctly.
### Advanced Example: Columns with flex and justify
We define custom placeholders for the column:
```sass
%justify-start {
justify-content: flex-start
}
%justify-center {
justify-content: center
}
%justify-end {
justify-content: flex-end
}
%flex-row {
flex-direction: row
div {
// Most streamlit components add width values as inline style. Make it fit the content so justify works.
width: fit-content !important
}
}
```
Now we register the new placeholders with `sal-column`:
```sass
$custom-classes: (
sal-column: (justify-start, justify-center, justify-end, flex-row),
)
```
After `streamlit-sal compile` the styles are prepared, we can move on with the app code.
Note that we here use the col elements and pass them as containers for the sal.column call.
To apply the same column style for any child elements you will need to extend on the col containers (col0, col1, col2)
```python
import streamlit as st
import streamlit_sal as sal
from streamlit_sal import sal_stylesheet
with sal_stylesheet():
col0, col1, col2 = st.columns(3)
with sal.column('justify-start', 'flex-row', container=col0):
col0.button("Left")
with sal.column('justify-center', 'flex-row', container=col1):
col1.button("Center")
with sal.column('justify-end', 'flex-row', container=col2):
col2.button("Right")
```
## How does it work?
Streamlit does not give users the possibility to add CSS ids or classes. However by adding a span markdown element
we can get the same effect:
```python
import streamlit as st
st.markdown(f"<span class='sal-button'></span>", unsafe_allow_html=True)
st.button("Hello world!")
```
Using `:has(.. span.sal-button)` and a sibling selector (`+`) we can now target that exact `st.button`:
```css
div:has(> div.stMarkdown > div[data-testid="stMarkdownContainer"] span.sal-button) + div button {
/*Add custom styles*/
}
```
### Building the selectors so you don't have to
SAL uses SASS to dynamically build all the required selectors using
a [component structure map](https://github.com/datarobot/streamlit-sal/blob/main/streamlit_sal/sass/_streamlit-component-map.scss)
and an `@each` loop.
The output CSS will be selectors just like the one seen above. All the defined SASS `%` placeholders are optional and
will not be part of the compiled when not set.
Any new custom classes that are registered properly will also be looped over during `streamlit-sal compile`.
## Troubleshooting
### No styling seems to apply
- Make sure you have wrapped your app code using `with sal_stylesheet():`
- Check that all placeholders in main.scss are defined correctly (`%` not `$`) and brackets are closed.
- Make sure you have run `streamlit-sal compile`
### The element I try to style has moved outside its container
- It might be a container element, pass it into sal using the `container=` arg [Read more](https://github.com/datarobot-oss/streamlit-sal/tree/main?tab=readme-ov-file#normal-elements-vs-container-elements)
Raw data
{
"_id": null,
"home_page": "https://github.com/datarobot-oss/streamlit-sal",
"name": "streamlit-sal",
"maintainer": null,
"docs_url": null,
"requires_python": "!=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "DataRobot Applications Team",
"author_email": "apps-oss@datarobot.com",
"download_url": "https://files.pythonhosted.org/packages/60/87/65e869bb34da44df0a73173df552429a28c6d63b6e2edf8777efee27e83a/streamlit_sal-0.1.5.tar.gz",
"platform": null,
"description": "# SAL - Style and Layout for Streamlit\n\n## What does it do?\n\nThis library lets you style Streamlit components with ease!\nHere is a quick example of what it can do for you:\n\n```sass\n// You define SASS style using a predefined placeholder\n%sal-button {\n border: 1px dashed antiquewhite\n}\n\n// Or you define SASS style using a custom placeholder (*)\n%btn-large {\n padding: 12px 18px\n p {\n font-weight:bold\n }\n}\n```\n\n(*[Read more about custom placeholders](https://github.com/datarobot-oss/streamlit-sal/tree/main?tab=readme-ov-file#add-custom-classes-to-sal-components))\n\nRun `streamlit-sal compile`\n\n```python\nimport streamlit as st\nimport streamlit_sal as sal\nfrom streamlit_sal import sal_stylesheet\n\nwith sal_stylesheet(move_sidebar_right=True):\n # The Streamlit sidebar is now on the right side of the view!\n\n # This wraps the 'btn-large' and general 'sal-button' styles onto the st.button in the context\n with sal.button('btn-large'):\n large_button = st.button('Big button')\n\n # It won't affect other usages of st.button\n normal_button = st.button('Streamlit button')\n```\n\nResult:\n\n\n\n> **Disclaimer**\n>\n> We cannot guarantee that this library will continue to work for every Streamlit release!\n\n## How to install it?\n\nInstall with `pip install streamlit-sal`\n\nFrom the root of your Streamlit app run: `streamlit-sal init`\n\nFill in the config variables for the desired style source and destination path.\nIt will then create a `main.scss` in the given source path and a `.streamlit_sal` in the project root path\n\nYou can test whether the `init` was successful by running `streamlit-sal compile` which should create a CSS file.\n\n## How to use it?\n\n(*[Make sure to initiate the library first](https://github.com/datarobot-oss/streamlit-sal/tree/main?tab=readme-ov-file#how-to-install-it))\n\nWrap your app code with the stylesheet:\n\n```python\nfrom streamlit_sal import sal_stylesheet\n\nwith sal_stylesheet():\n # Your app code goes here!\n```\n\nThis will render a streamlit markdown element with a style tag containing the compiled CSS before your code\n\n### Add placeholders, compile and render\n\nNavigate to your `main.scss` and start adding the style placeholders that you need. The available predefined\nplaceholders can be found [here](https://github.com/datarobot/streamlit-sal/PLACEHOLDERS.md). A rule of thumb for\nplaceholders is that every Streamlit component name\nexists with a `sal-` prefix and underscores are replaced by dashes (`st.download_button` -> `sal-download-button`)\n\nLet's take an example for st.button. We add a new border style for the existing placeholder:\n\n```sass\n%sal-button {\n border: 1px dashed red\n}\n```\n\nNow we run `streamlit-sal compile` to create the CSS stylesheet sal-stylesheet.css (default name)\n\nThe CSS will now apply to all st.button elements that are wrapped with sal.button():\n\n```python\nimport streamlit as st\nimport streamlit_sal as sal\nfrom streamlit_sal import sal_stylesheet\n\nwith sal_stylesheet():\n # This wraps the default 'sal-button' styles onto the st.button within the context\n with sal.button():\n st.button('Red Border Button')\n```\n\n### Add custom classes to SAL components\n\nSAL can easily be extended with additional custom placeholders/classes. Though it is important to register the\nnew placeholders with the correct components.\n\n```sass\n// Define a custom placeholder (avoid sal- prefix to minimize risk of duplicates)\n%btn-large {\n padding: 12px 18px\n p {\n font-weight:bold\n }\n}\n```\n\nThe above placeholder will not be compiled into the final CSS stylesheet yet. It first needs to be registered\nto the sal-button. You can find the `$custom-classes` variable at the bottom of your `main.scss`:\n\n```sass\n$custom-classes: (\n sal-button: (btn-large),\n)\n```\n\nMultiple placeholders can be added to the same components and even reused between multiple components:\n\n```sass\n$custom-classes: (\n sal-button: (btn-large, btn-primary),\n sal-download-button: (btn-primary),\n)\n```\n\n\n### Normal elements vs container elements\nMost elements behave the same, but there are some container-type elements that need special treatment.\nFor these elements you will need to pass down the container to SAL to make it work:\n- `with sal.column(..., container=col1): # From col0, col1 = st.columns(2)`\n- `with sal.popover_content(..., container=container): # From container = st.container()`\n\nSAL should warn you when a container element was not used correctly.\n\n\n### Advanced Example: Columns with flex and justify\n\n\n\nWe define custom placeholders for the column:\n\n```sass\n%justify-start {\n justify-content: flex-start\n}\n\n%justify-center {\n justify-content: center\n}\n\n%justify-end {\n justify-content: flex-end\n}\n\n%flex-row {\n flex-direction: row\n\n div {\n // Most streamlit components add width values as inline style. Make it fit the content so justify works.\n width: fit-content !important\n }\n}\n```\n\nNow we register the new placeholders with `sal-column`:\n\n```sass\n$custom-classes: (\n sal-column: (justify-start, justify-center, justify-end, flex-row),\n)\n```\n\nAfter `streamlit-sal compile` the styles are prepared, we can move on with the app code.\nNote that we here use the col elements and pass them as containers for the sal.column call.\nTo apply the same column style for any child elements you will need to extend on the col containers (col0, col1, col2)\n\n```python\nimport streamlit as st\nimport streamlit_sal as sal\nfrom streamlit_sal import sal_stylesheet\n\nwith sal_stylesheet():\n col0, col1, col2 = st.columns(3)\n with sal.column('justify-start', 'flex-row', container=col0):\n col0.button(\"Left\")\n with sal.column('justify-center', 'flex-row', container=col1):\n col1.button(\"Center\")\n with sal.column('justify-end', 'flex-row', container=col2):\n col2.button(\"Right\")\n```\n\n## How does it work?\n\nStreamlit does not give users the possibility to add CSS ids or classes. However by adding a span markdown element\nwe can get the same effect:\n\n```python\nimport streamlit as st\n\nst.markdown(f\"<span class='sal-button'></span>\", unsafe_allow_html=True)\nst.button(\"Hello world!\")\n```\n\nUsing `:has(.. span.sal-button)` and a sibling selector (`+`) we can now target that exact `st.button`:\n\n```css\ndiv:has(> div.stMarkdown > div[data-testid=\"stMarkdownContainer\"] span.sal-button) + div button {\n /*Add custom styles*/\n}\n```\n\n### Building the selectors so you don't have to\n\nSAL uses SASS to dynamically build all the required selectors using\na [component structure map](https://github.com/datarobot/streamlit-sal/blob/main/streamlit_sal/sass/_streamlit-component-map.scss)\nand an `@each` loop.\nThe output CSS will be selectors just like the one seen above. All the defined SASS `%` placeholders are optional and\nwill not be part of the compiled when not set.\n\nAny new custom classes that are registered properly will also be looped over during `streamlit-sal compile`.\n\n\n## Troubleshooting\n\n### No styling seems to apply\n- Make sure you have wrapped your app code using `with sal_stylesheet():`\n- Check that all placeholders in main.scss are defined correctly (`%` not `$`) and brackets are closed. \n- Make sure you have run `streamlit-sal compile`\n\n### The element I try to style has moved outside its container\n- It might be a container element, pass it into sal using the `container=` arg [Read more](https://github.com/datarobot-oss/streamlit-sal/tree/main?tab=readme-ov-file#normal-elements-vs-container-elements)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Style and layout for your Streamlit app using SASS",
"version": "0.1.5",
"project_urls": {
"Documentation": "https://github.com/datarobot-oss/streamlit-sal",
"Homepage": "https://github.com/datarobot-oss/streamlit-sal",
"Repository": "https://github.com/datarobot-oss/streamlit-sal"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9274a23a69b1a73eaeccf2744af6f00870cb7bfc1bae506b7fef521e8ee635d9",
"md5": "8cb1c7feaa60cecd2434242d8bf3f6af",
"sha256": "6c8a3f0193507103d8e8d2d64aa5c3ec5f18d6e31e29a0a7ddfe20b0bd79dd18"
},
"downloads": -1,
"filename": "streamlit_sal-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8cb1c7feaa60cecd2434242d8bf3f6af",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "!=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,>=3.8",
"size": 28408,
"upload_time": "2024-08-27T07:42:30",
"upload_time_iso_8601": "2024-08-27T07:42:30.947631Z",
"url": "https://files.pythonhosted.org/packages/92/74/a23a69b1a73eaeccf2744af6f00870cb7bfc1bae506b7fef521e8ee635d9/streamlit_sal-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "608765e869bb34da44df0a73173df552429a28c6d63b6e2edf8777efee27e83a",
"md5": "6ea9e34ac9b78a0045251c51253ab291",
"sha256": "39842cb7496655717313636b0d53c616d3212ff35c612a24e28a91e11c94120d"
},
"downloads": -1,
"filename": "streamlit_sal-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "6ea9e34ac9b78a0045251c51253ab291",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,>=3.8",
"size": 28438,
"upload_time": "2024-08-27T07:42:33",
"upload_time_iso_8601": "2024-08-27T07:42:33.462663Z",
"url": "https://files.pythonhosted.org/packages/60/87/65e869bb34da44df0a73173df552429a28c6d63b6e2edf8777efee27e83a/streamlit_sal-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-27 07:42:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "datarobot-oss",
"github_project": "streamlit-sal",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "streamlit-sal"
}
JSON
