# Dash Overview

## Dash: The Basics

Dash is a Python-based dashboarding library that makes it easy to build detailed, Enterprise-grade dashboards and data apps. 

To understand Dash, there are three basic concepts to understand:

1. A Dash App instance: a single running instance of your data app. 
2. The app layout: how to configure what is actually displayed in your dash app.
3. Callbacks: how to make your dash app interactive. 

To see how each of these come together, consider the following simplest example of an interactive Dash application:

```python
from dash import Dash, html, dcc, callback, Output, Input
import plotly.express as px
import pandas as pd

df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/gapminder_unfiltered.csv')

# (1) The Dash App instance
app = Dash(__name__)

# (2) The app layout
app.layout = html.Div([
    html.H1(children='Title of Dash App', style={'textAlign':'center'}),
    dcc.Dropdown(df.country.unique(), 'Canada', id='dropdown-selection'),
    dcc.Graph(id='graph-content')
])

# (3) A callback
@callback(
    Output('graph-content', 'figure'),
    Input('dropdown-selection', 'value')
)
def update_graph(value):
    dff = df[df.country==value]
    return px.line(dff, x='year', y='pop')

if __name__ == '__main__':
    app.run(debug=True)
```

## (1) The Dash App Instance

To create a new Dash app instance, all you need is the following code (in a file `app.py`

```python
from dash import Dash
app = Dash(__name__)

# Code elided from above

if __name__ == '__main__':
    app.run(debug=True)
```

Running this code with `python app.py` will start a server that serves a blank webpage. Congrats, that's your first data app! But because you havent set a layout, or configured any callbacks, it's not super interesting. 

## (2) The App Layout

Ok, so you actually want something to be displayed. Let's add in more code - to set the layout. 

{% code lineNumbers="true" %}

```python
from dash import Dash, html, dcc, callback, Output, Input
import plotly.express as px
import pandas as pd

df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/gapminder_unfiltered.csv')

# (1) The Dash App instance
app = Dash(__name__)

# (2) The app layout
app.layout = html.Div([
    html.H1(children='Title of Dash App', style={'textAlign':'center'}),
    dcc.Dropdown(df.country.unique(), 'Canada', id='dropdown-selection'),
    dcc.Graph(id='graph-content')
])

if __name__ == '__main__':
    app.run(debug=True)
```

{% endcode %}

If you run this code, a webpage with some content will be served! It will have two things:

1. A title - set on line 12. The title is set to `Title of Dash App` and some additional styling is added to center the text.
2. A dropdown - set on line 13. The possible options of this dropdown are the various countries in the dataframe defined on line 5, and the starting value is `Canada`

`app.layout` is how you actually tell the Dash app what to display. You can nest components like div's (which are just containers), or `H1` (which is a large header) or `Dropdown` (which lets you select from a variety of options). See the Dash documentation for [all components.](https://dash.plotly.com/dash-core-components)

However, nothing happens when you change the dropdown item that is selected! That's no good -- we want to update the graph component defined on line 14...

#### (3) A Callback

Callbacks are how you add interactivity to your application. By registering a series of Outputs that change when a different set of Inputs change, you can make pieces of your application respond changes in other pieces of your application.

{% code lineNumbers="true" %}

```python
from dash import Dash, html, dcc, callback, Output, Input
import plotly.express as px
import pandas as pd

df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/gapminder_unfiltered.csv')

# (1) The Dash App instance
app = Dash(__name__)

# (2) The app layout
app.layout = html.Div([
    html.H1(children='Title of Dash App', style={'textAlign':'center'}),
    dcc.Dropdown(df.country.unique(), 'Canada', id='dropdown-selection'),
    dcc.Graph(id='graph-content')
])

# (3) A callback
@callback(
    Output('graph-content', 'figure'),
    Input('dropdown-selection', 'value')
)
def update_graph(value):
    dff = df[df.country==value]
    return px.line(dff, x='year', y='pop')

if __name__ == '__main__':
    app.run(debug=True)
```

{% endcode %}

Here's what's happening above:

1. On line 18, a callback is registered. The callback is the function `update_graph`
2. The Input to the callback is the `value` of the `dropdown-selection` component - defined on line 13. 
3. The Output from the callback is the `figure` of the `graph-content` component, defined on line 14. 

Here's what this accomplishes: 

1. When the `value` of the component with id `dropdown-selection` changes because the user selects something different from the dropdown, the function `update-graph` changes. 
2. When this function runs, the `value` that is passed to the function as it's singular argument is the new value of the Dropdown the user has selected on the frontend. 
3. This function runs, creates a new Plotly line chart, and then returns it. 
4. This returned line chart is written to the `graph-content` component, specifically for it's `figure` value, which then updates on the frontend. 

By reading the documentation for a component, you can see what the correct props are to write to with outputs!

## Understanding More About Dash

New to writing Dash applications and looking to understand more? Check out the Dash docs to learn more [core concepts.](https://dash.plotly.com/layout)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.trymito.io/mito-for-dash/dash-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.