|
| 1 | +# Components |
| 2 | + |
| 3 | +You don’t have to start from scratch: components are reusable pieces of code (functions, themes, snippets, etc.) that make it quicker to update page layout and appearance, and add common page content. |
| 4 | + |
| 5 | +The Observable CLI offers three flavors of components: [layout helpers](#layout-helpers), [Observable Plot snippets](#observable-plot-snippets), and [Observable Inputs](#observable-inputs). |
| 6 | + |
| 7 | +## Layout helpers |
| 8 | + |
| 9 | +A collection of elements useful for formatting page content: themes, `card` and `grid` CSS classes, and the `resize` function. |
| 10 | + |
| 11 | +### Themes |
| 12 | + |
| 13 | +<!-- TODO update link to themes gallery layout/themes.md page once added--> |
| 14 | +Observable Markdown offers a number of [built-in themes](./config#theme) that you can compose to create, say, wide pages with an alternative dark color theme: |
| 15 | + |
| 16 | +```js run=false |
| 17 | +theme: ["dark", "alt", "wide"] |
| 18 | +``` |
| 19 | + |
| 20 | +The code above, when included in the [config file](./config), specifies the default theme for the project. In addition, you can specify the theme for a single page in its [front matter](markdown#front-matter): |
| 21 | + |
| 22 | +```yaml |
| 23 | +--- |
| 24 | +theme: [dark, alt, wide] |
| 25 | +--- |
| 26 | +``` |
| 27 | + |
| 28 | +You are not limited to the built-in themes. For complete control over the design of your project, see the [style option](./config/#style) instead. |
| 29 | + |
| 30 | +### Grid |
| 31 | + |
| 32 | +The included [`grid`](./layout/grid) CSS classes make it easier to control how page content is arranged. |
| 33 | + |
| 34 | +<div class="grid grid-cols-2"> |
| 35 | + <div class="card"><h1>A</h1>1 × 1</div> |
| 36 | + <div class="card grid-rowspan-2"><h1>B</h1>1 × 2</div> |
| 37 | + <div class="card"><h1>C</h1>1 × 1</div> |
| 38 | + <div class="card grid-colspan-2"><h1>D</h1>1 × 2</div> |
| 39 | +</div> |
| 40 | + |
| 41 | +```html run=false |
| 42 | +<div class="grid grid-cols-2"> |
| 43 | + <div class="card"><h1>A</h1>1 × 1</div> |
| 44 | + <div class="card grid-rowspan-2"><h1>B</h1> 1 × 2</div> |
| 45 | + <div class="card"><h1>C</h1>1 × 1</div> |
| 46 | + <div class="card grid-colspan-2"><h1>D</h1>1 × 2</div> |
| 47 | +</div> |
| 48 | +``` |
| 49 | + |
| 50 | +### Card |
| 51 | + |
| 52 | +The [`card`](./layout/card) CSS class has default styles that help create a card: container borders, background color, padding and optional titles and subtitles. |
| 53 | + |
| 54 | +<div class="grid grid-cols-2"> |
| 55 | + <div class="card"> |
| 56 | + <h2>A card title</h2> |
| 57 | + <h3>A card subtitle</h3> |
| 58 | + ${ |
| 59 | + Plot.plot({ |
| 60 | + marks: [ |
| 61 | + Plot.dot(penguins, {x: "body_mass_g", y: "flipper_length_mm"}) |
| 62 | + ] |
| 63 | + }) |
| 64 | + } |
| 65 | + </div> |
| 66 | + <div class="card"> |
| 67 | + <p>Tortor condimentum lacinia quis vel eros. Arcu risus quis varius quam quisque id. Magnis dis parturient montes nascetur ridiculus mus mauris. Porttitor leo a diam sollicitudin. Odio facilisis mauris sit amet massa vitae tortor. Nibh venenatis cras sed felis eget velit aliquet sagittis. Ullamcorper sit amet risus nullam eget felis eget nunc. In egestas erat imperdiet sed euismod nisi porta lorem mollis. A erat nam at lectus urna duis convallis. Id eu nisl nunc mi ipsum faucibus vitae. Purus ut faucibus pulvinar elementum integer enim neque volutpat ac.</p> |
| 68 | + </div> |
| 69 | +</div> |
| 70 | + |
| 71 | +```html run=false |
| 72 | +<div class="grid grid-cols-2"> |
| 73 | + <div class="card"> |
| 74 | + <h2>A card title</h2> |
| 75 | + <h3>A card subtitle</h3> |
| 76 | + ${ |
| 77 | + Plot.plot({ |
| 78 | + marks: [ |
| 79 | + Plot.dot(penguins, {x: "body_mass_g", y: "flipper_length_mm"}) |
| 80 | + ] |
| 81 | + }) |
| 82 | + } |
| 83 | + </div> |
| 84 | + <div class="card"> |
| 85 | + <p>Tortor condimentum lacinia quis vel eros. Arcu risus quis varius quam quisque id. Magnis dis parturient montes nascetur ridiculus mus mauris. Porttitor leo a diam sollicitudin. Odio facilisis mauris sit amet massa vitae tortor. Nibh venenatis cras sed felis eget velit aliquet sagittis. Ullamcorper sit amet risus nullam eget felis eget nunc. In egestas erat imperdiet sed euismod nisi porta lorem mollis. A erat nam at lectus urna duis convallis. Id eu nisl nunc mi ipsum faucibus vitae. Purus ut faucibus pulvinar elementum integer enim neque volutpat ac.</p> |
| 86 | + </div> |
| 87 | +</div> |
| 88 | +``` |
| 89 | + |
| 90 | +### Resize |
| 91 | + |
| 92 | +The [`resize`](./layout/resize) function automatically recomputes a DOM element (often, a chart) when the dimensions of its parent container change. |
| 93 | + |
| 94 | +Resize exists in the Observable standard library, or can be imported explicitly: |
| 95 | + |
| 96 | +```js echo |
| 97 | +import {resize} from "npm:@observablehq/stdlib"; |
| 98 | +``` |
| 99 | + |
| 100 | +<div> |
| 101 | + ${resize((width) => Plot.barY([9, 4, 8, 1, 11, 3, 4, 2, 7, 5]).plot({width}))} |
| 102 | +</div> |
| 103 | + |
| 104 | +```html run=false |
| 105 | +<div> |
| 106 | + ${resize((width) => Plot.barY([9, 4, 8, 1, 11, 3, 4, 2, 7, 5]).plot({width}))} |
| 107 | +</div> |
| 108 | +``` |
| 109 | + |
| 110 | +## Observable Plot snippets |
| 111 | + |
| 112 | +[Observable Plot](https://observablehq.com/plot/) is a free, open source JavaScript library for concise and expressive data visualization, built by Observable. |
| 113 | + |
| 114 | +Several examples of Observable Plot code are included in this documentation, covering some common chart types including area charts ([stacked](./charts/area#stacked-area-chart) and [band area](./charts/area#band-area-chart)), bar charts ([sorted](./charts/bar#sorted-bar-chart), [temporal](./charts/bar#temporal-bar-chart), and [weighted](./charts/bar#weighted-top-10-bar-chart)), line charts ([single-series](./charts/line#basic-line-chart), [multi-series](./charts/line#multi-series-line-chart) and [moving average](./charts/line#moving-average-line-chart)), [scatterplots](./charts/dot#scatterplot), and more. See [Observable Plot’s gallery](https://observablehq.com/@observablehq/plot-gallery) for even more examples. |
| 115 | + |
| 116 | +All examples use common datasets that are loaded when referenced by name, such as the `weather` dataset in the code snippet below. |
| 117 | + |
| 118 | +```js echo |
| 119 | +Plot.plot({ |
| 120 | + marks: [ |
| 121 | + Plot.cell(weather, { |
| 122 | + x: d => d.date.getUTCDate(), |
| 123 | + y: d => d.date.getUTCMonth(), |
| 124 | + fill: "temp_max" |
| 125 | + }) |
| 126 | + ] |
| 127 | +}) |
| 128 | +``` |
| 129 | + |
| 130 | +If the chart type you want to add is not included as a snippet here, don’t sweat - a great number of examples (in both [Observable Plot](https://observablehq.com/@observablehq/plot-gallery) and [D3](https://observablehq.com/@d3/gallery)) are available to explore and reuse. |
| 131 | + |
| 132 | +**Can I use other data visualization libraries?** Absolutely. Use any other visualization library you like by [importing from npm](./javascript/imports). |
| 133 | + |
| 134 | +## Observable Inputs |
| 135 | + |
| 136 | +The [Observable Inputs](./lib/inputs) library provides a suite of lightweight interface components — buttons, sliders, dropdowns, checkboxes, and the like — that viewers can update to explore interactive displays (for example, selecting only a few of many categories to show in a bar chart). |
| 137 | + |
| 138 | +The [radio input](./inputs/radio) prompts a user to select a penguin species: |
| 139 | + |
| 140 | +```js echo |
| 141 | +const pickSpecies = view(Inputs.radio(["Adelie", "Chinstrap", "Gentoo"], {value: "Gentoo", label: "Penguin species:"})) |
| 142 | +``` |
| 143 | + |
| 144 | +The value of `pickSpecies` (<tt>="${pickSpecies}"</tt>) can then be accessed elsewhere in the page, as a parameter in other computations, and to create interactive charts, tables or text with [inline expressions](./javascript#inline-expressions). |
0 commit comments