- **`persisted_props`** (list of strings; optional): These are the props whose values will persist. Typically this defaults to all user-editable props, which in many cases is just one (ie `'value'`). `dash-table` has many props users can edit, and all of them except `'data'` are included here by default. Sometimes only a *part* of a prop is saved; this happens with table headers, which are only part of the `columns` prop. The corresponding `persisted_props` value is `'columns.name'`. In the following example, notice that a callback that depends on persisted values receives those persisted values, even if the layout initially provided something else. Also the city is persisted in `localStorage` so will be saved indefinitely, but the neighborhood - which remembers a different value for each city - resets if you open the page in a new tab. '''), rc.Syntax(examples['persistence.py'][0]), rc.Example(examples['persistence.py'][1]), rc.Markdown(''' ## Explicitly clearing saved data Persistence continues (subject to `persistence_type`) as long as the component `id`, the `persistence` value, and the prop provided by the server when creating or updating the *entire* component has the same value as it had before the user changed it. But if you have a callback whose `Output` is the specific persisted prop itself, that takes precedence over any saved value. This lets you reset user edits, using `PreventUpdate` or `dash.no_update` until you detect the reset condition. '''), rc.Syntax(examples['persistence_clear.py'][0]), rc.Example(examples['persistence_clear.py'][1]), rc.Markdown(''' ## For component developers
rc.Markdown(''' New in Dash 1.11.0! The pattern-matching callback selectors `MATCH`, `ALL`, & `ALLSMALLER` allow you to write callbacks that respond to or update an arbitrary or dynamic number of components. ## Simple Example with `ALL` This example renders an arbitrary number of `dcc.Dropdown` elements and the callback is fired whenever any of the `dcc.Dropdown` elements change. Try adding a few dropdowns and selecting their values to see how the app updates. '''), rc.Syntax(examples['simple_all.py'][0]), rc.Example(examples['simple_all.py'][1], style={'overflowX': 'initial'}), rc.Markdown(''' Some notes about this example: - Notice how the `id` in `dcc.Dropdown` is a _dictionary_ rather than a _string_. This is a new feature that we enabled for pattern-matching callbacks (previously, IDs had to be strings). - In our second callback, we have `Input({'type': 'dropdown', 'index': ALL}, 'value')`. This means "match any input that has an ID dictionary where `'type'` is `'dropdown'` and `'index'` is _anything_. Whenever the `value` property of any of the dropdowns change, send _all_ of their values to the callback." - The keys & values of the ID dictionary (`type`, `index`, `filter-dropdown`) are arbitrary. This could've be named `{'foo': 'bar', 'baz': n_clicks}`. - However, for readability, we recommend using keys like `type`, `index`, or `id`. `type` can be used to refer to the class or set dynamic components and `index` or `id` could be used to refer _which_ component you are matching within that set. In this example, we just have a single set of dynamic
# -*- coding: utf-8 -*- import dash_core_components as dcc import dash_html_components as html from dash_docs import styles from dash_docs import tools from dash_docs import reusable_components as rc examples = tools.load_examples(__file__) layout = html.Div([ html.H1('dcc.ConfirmDialogProvider Documentation'), rc.Markdown(''' Send a <dccLink href="/dash-core-components/confirmdialog" children="ConfirmDialog"/> when the user clicks the children of this component, usually a button. '''), rc.Syntax(examples['confirm_provider.py'][0]), rc.Example(examples['confirm_provider.py'][1]), html.H1('dcc.ConfirmDialogProvider Reference'), rc.ComponentReference('ConfirmDialogProvider') ])
The `dcc.Graph` component has four attributes that can change through user-interaction: `hoverData`, `clickData`, `selectedData`, `relayoutData`. These properties update when you hover over points, click on points, or select regions of points in a graph. '''), rc.Syntax( examples['graph_callbacks_simple.py'][0], summary=""" Here's an simple example that prints these attributes in the screen. """), rc.Example(examples['graph_callbacks_simple.py'][1]), html.Hr(), html.H3('Update Graphs on Hover'), rc.Syntax(examples['getting_started_crossfilter.py'][0], summary=""" Let's update our world indicators example from the previous chapter by updating time series when we hover over points in our scatter plot. """), rc.Example(examples['getting_started_crossfilter.py'][1]), rc.Markdown(''' Try mousing over the points in the scatter plot on the left. Notice how the line graphs on the right update based off of the point that you are hovering over.
import dash_html_components as html from dash_docs import styles from dash_docs import tools from dash_docs import reusable_components as rc examples = tools.load_examples(__file__) layout = html.Div(children=[ html.H1('Button Examples and Reference'), html.H2('Button Basic Example'), rc.Markdown("An example of a default button without any extra properties \ and `n_clicks` in the callback. `n_clicks` is an integer that represents \ that number of times the button has been clicked. Note that the original \ value is `None`."), rc.Syntax(examples['button_basic.py'][0]), rc.Example(examples['button_basic.py'][1]), html.Br(), html.H2([ 'Determining which Button Changed with ', html.Code('callback_context') ]), rc.Markdown("This example utilizes the `dash.callback_context` property, \ to determine which input was changed."), rc.Syntax(examples['button_ctx.py'][0]), rc.Example(examples['button_ctx.py'][1]), html.Br(), html.H2('Button Properties'), rc.ComponentReference('Button', html) ])
from dash_docs import tools from dash_docs import reusable_components as rc examples = tools.load_examples(__file__) layout = html.Div([ html.H1('Advanced Callbacks'), rc.Markdown(''' ## Catching errors with `PreventUpdate` In certain situations, you don't want to update the callback output. You can achieve this by raising a `PreventUpdate` exception in the callback function. '''), rc.Syntax(examples['prevent_update_button.py'][0]), rc.Example(examples['prevent_update_button.py'][1]), rc.Markdown(''' ## Displaying errors with `dash.no_update` This example illustrates how you can show an error while keeping the previous input, using `dash.no_update` to update the output partially. '''), rc.Syntax(examples['prevent_update.py'][0]), rc.Example(examples['prevent_update.py'][1]), rc.Markdown(''' ## Determining which `Input` has fired with `dash.callback_context` In addition to event properties like `n_clicks` that change whenever an event happens (in this case a click), there is a global variable `dash.callback_context`, available only inside a callback. It has properties:
rc.Syntax(examples['getting_started_layout_1.py'][0], summary=''' To get started, create a file named `app.py` with the following code: '''), rc.Markdown(''' Run the app with ``` $ python app.py ...Running on http://127.0.0.1:8050/ (Press CTRL+C to quit) ``` and visit [http://127.0.0.1:8050/](http://127.0.0.1:8050/) in your web browser. You should see an app that looks like this. '''), rc.Example(examples['getting_started_layout_1.py'][1]), rc.Markdown(''' Note: 1. The `layout` is composed of a tree of "components" like `html.Div` and `dcc.Graph`. 2. The `dash_html_components` library has a component for every HTML tag. The `html.H1(children='Hello Dash')` component generates a `<h1>Hello Dash</h1>` HTML element in your application. 3. Not all components are pure HTML. The `dash_core_components` describe higher-level components that are interactive and are generated with JavaScript, HTML, and CSS through the React.js library. 4. Each component is described entirely through keyword attributes. Dash is _declarative_: you will primarily describe your application through these attributes. 5. The `children` property is special. By convention, it's always the
# -*- coding: utf-8 -*- import dash_core_components as dcc import dash_html_components as html from dash_docs import styles from dash_docs import tools from dash_docs import reusable_components as rc examples = tools.load_examples(__file__) layout = html.Div([ html.H1('ConfirmDialog component'), rc.Markdown(''' ConfirmDialog is used to display the browser's native "confirm" modal, with an optional message and two buttons ("OK" and "Cancel"). This ConfirmDialog can be used in conjunction with buttons when the user is performing an action that should require an extra step of verification. See <dccLink href="/dash-core-components/confirmdialogprovider" children="dcc.ConfirmDialogProvider"/> for an easier way to display an alert when clicking on an item. '''), rc.Syntax(examples['confirm.py'][0]), rc.Example(examples['confirm.py'][1]), html.H2('dcc.ConfirmDialog Properties'), rc.ComponentReference('ConfirmDialog') ])
# -*- coding: utf-8 -*- import dash_core_components as dcc import dash_html_components as html from dash_docs import styles from dash_docs import tools from dash_docs import reusable_components as rc examples = tools.load_examples(__file__) layout = html.Div(children=[ html.H1('Input Examples and Reference'), html.H2('Supported Input Types'), rc.Syntax(examples['input_all_types.py'][0]), rc.Example(examples['input_all_types.py'][1]), html.Br(), html.H2('Debounce delays the Input processing'), rc.Syntax(examples['input-basic.py'][0]), rc.Example(examples['input-basic.py'][1]), html.Br(), html.H2('Number Input'), rc.Markdown(""" _Fixed and enhanced in Dash v1.1.0_ Number type is now close to native HTML5 `input` behavior across browsers. We also apply a strict number casting in callbacks: valid number converts into corresponding number types, and invalid number converts into None. E.g. `dcc.Input(id='range', type='number', min=2, max=10, step=1)` typing 3 and 11 will return respectively integer three and None in Python callbacks.
the `contents` property of the `dcc.Upload` component. `contents` is a base64 encoded string that contains the files contents, no matter what type of file: text files, images, zip files, excel spreadsheets, etc. '''), rc.Syntax(examples['upload-datafile.py'][0], summary=rc.Markdown(''' Here's an example that parses CSV or Excel files and displays the results in a table. Note that this example uses the `DataTable` from the [dash-table](https://github.com/plotly/dash-table) project. ''')), rc.Example(examples['upload-datafile.py'][1]), html.Hr(), rc.Syntax(examples['upload-image.py'][0], summary=rc.Markdown(''' This next example responds to image uploads by displaying them in the app with the `html.Img` component. ''')), rc.Example(examples['upload-image.py'][1]), rc.Syntax(examples['upload-gallery.py'][0], summary=rc.Markdown(''' The `children` attribute of the `Upload` component accepts any Dash component. Clicking on the children element will trigger the upload action, as will dragging and dropping files. Here are a few different ways that you could style the upload component using standard dash components. ''')),
text files , etc. The component opens a download dialog when the data property changes. Note that the following examples make use of the `prevent_initial_call` attribute to prevent the callbacks from being triggered when the app inputs are initially rendered. See <dccLink href="../\ advanced-callbacks#prevent-callbacks-from-being-executed-on-initial-\ load" children="Advanced Callbacks"/>. for more details. '''), html.H3('Downloading Content as Strings'), rc.Syntax(examples['download-text.py'][0], summary=rc.Markdown(''' Here is an example show how to download content as a string, \ while showing the raw JSON: ''')), rc.Example(examples['download-text.py'][1]), html.Hr(), html.H3('Download Dataframe as CSV file'), rc.Syntax(examples['download-dataframe-csv.py'][0], summary=rc.Markdown(''' For downloading dataframes, the many pandas export methods are supported. Below we are downloading a dataframe as a CSV: ''')), rc.Example(examples['download-dataframe-csv.py'][1]), html.Hr(), html.H3('Download Dataframe as Excel file'), rc.Syntax(examples['download-dataframe-xlxs.py'][0], summary=rc.Markdown(''' To download a dataframe as an Excel file with pandas, add `xlsxwriter` or `openpyxl` as an app dependency: ''')),
from dash_docs import styles from dash_docs import tools from dash_docs import reusable_components as rc examples = tools.load_examples(__file__) layout = html.Div(children=[ html.H3('dcc.Textarea Documentation'), dcc.Markdown( ''' `dcc.Textarea` is a wrapper around the [<textarea/> HTML component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea). It is like a `dcc.Input` except that allows for multiple lines of text. ''' ), html.H2('Simple dcc.Textarea Example'), rc.Syntax(examples['textarea_basic.py'][0]), rc.Example(examples['textarea_basic.py'][1]), html.H2('Update dcc.Textarea callback on button press'), rc.Syntax(examples['textarea_state.py'][0]), rc.Example(examples['textarea_state.py'][1]), html.H2('dcc.Textarea Properties'), rc.ComponentReference('Textarea') ])
import dash_core_components as dcc import dash_html_components as html from dash_docs import styles from dash_docs import tools from dash_docs import reusable_components as rc examples = tools.load_examples(__file__) layout = html.Div([ html.H1('dcc.Loading Component Documentation'), rc.Markdown(''' Here’s a simple example that wraps the outputs for a couple of `Input` components in the `Loading` component. As you can see, you can define the type of spinner you would like to show (refer to the reference table below for all possible types of spinners). You can modify other attributes as well, such as `fullscreen=True` if you would like the spinner to be displayed fullscreen. Notice that, the Loading component traverses all of its children to find a loading state, as demonstrated in the second callback, so that even nested children will get picked up. '''), rc.Syntax(examples['loading_component.py'][0]), rc.Example(examples['loading_component.py'][1]), rc.Markdown(''' Please also check out <dccLink href="/loading-states" children="this section on loading states"/> if you want a more customizable experience. '''), html.H2('dcc.Loading Properties'), rc.ComponentReference('Loading') ])
*** ## A simple example Below are two examples of using clientside callbacks to update a graph in conjunction with a `dcc.Store` component. In these examples, we update a `dcc.Store` component on the backend; to create and display the graph, we have a clientside callback in the frontend that adds some extra information about the layout that we specify using the radio buttons under "Graph scale". '''), rc.Syntax(examples['graph_update_fe_be.py'][0]), rc.Example(examples['graph_update_fe_be.py'][1]), rc.Markdown(''' Note that, in this example, we are manually creating the `figure` dictionary by extracting the relevant data from the dataframe. This is what gets stored in our `dcc.Store` component; expand the "Contents of figure storage" above to see exactly what is used to construct the graph. ### Using Plotly Express to generate a figure Plotly Express enables you to create one-line declarations of figures. When you create a graph with, for example, `plotly_express.Scatter`, you get a dictionary as a return value. This dictionary is in the same shape as the `figure`
import dash_html_components as html from dash_docs import tools from dash_docs import reusable_components as rc examples = tools.load_examples(__file__) layout = html.Div([ html.H1('dcc.Store'), rc.Markdown(''' The `dcc.Store` component is used to store JSON data in the browser. '''), html.H2('Store clicks example'), rc.Syntax(examples['store_clicks.py'][0]), rc.Example(examples['store_clicks.py'][1]), html.H2('Share data between callbacks'), rc.Syntax(examples['store_share.py'][0]), rc.Example(examples['store_share.py'][1]), rc.Markdown(''' ## Storage Limitations - The maximum browser [storage space](https://demo.agektmr.com/storage/) is determined by the following factors: - Mobile or laptop - The browser, under which a sophisticated algorithm is implemented within *Quota Management* - Storage encoding where UTF-16 can end up saving only half of the size of UTF-8 - It's generally safe to store up to 2MB in most environments, and 5~10MB in most desktop-only applications. - `modified_timestamp` is read only.