|
| 1 | +--- |
| 2 | +title: Component fundamentals |
| 3 | +--- |
| 4 | + |
| 5 | +- script (module) / template / style (rough overview) |
| 6 | +- `$props` / `$state` (in the context of components) |
| 7 | + |
| 8 | +Components are the building blocks of Svelte applications. They are written into `.svelte` files, using a superset of HTML. |
| 9 | + |
| 10 | +All three sections — script, styles and markup — are optional. |
| 11 | + |
| 12 | +```svelte |
| 13 | +<script> |
| 14 | + // logic goes here |
| 15 | +</script> |
| 16 | +
|
| 17 | +<!-- markup (zero or more items) goes here --> |
| 18 | +
|
| 19 | +<style> |
| 20 | + /* styles go here */ |
| 21 | +</style> |
| 22 | +``` |
| 23 | + |
| 24 | +## <script> |
| 25 | + |
| 26 | +A `<script>` block contains JavaScript (or TypeScript, when adding the `lang="ts"` attribute) that runs when a component instance is created. Variables declared (or imported) at the top level are 'visible' from the component's markup. |
| 27 | + |
| 28 | +### Public API of a component |
| 29 | + |
| 30 | +Svelte uses the `$props` rune to declare _properties_ or _props_, which means describing the public interface of the component which becomes accessible to consumers of the component. |
| 31 | + |
| 32 | +> `$props` is one of several runes, which are special hints for Svelte's compiler to make things reactive. |
| 33 | +
|
| 34 | +```svelte |
| 35 | +<script> |
| 36 | + let { foo, bar, baz } = $props(); |
| 37 | +
|
| 38 | + // Values that are passed in as props |
| 39 | + // are immediately available |
| 40 | + console.log({ foo, bar, baz }); |
| 41 | +</script> |
| 42 | +``` |
| 43 | + |
| 44 | +You can specify a fallback value for a prop. It will be used if the component's consumer doesn't specify the prop on the component when instantiating the component, or if the passed value is `undefined` at some point. |
| 45 | + |
| 46 | +```svelte |
| 47 | +<script> |
| 48 | + let { foo = 'optional default initial value' } = $props(); |
| 49 | +</script> |
| 50 | +``` |
| 51 | + |
| 52 | +To get all properties, use rest syntax: |
| 53 | + |
| 54 | +```svelte |
| 55 | +<script> |
| 56 | + let { a, b, c, ...everythingElse } = $props(); |
| 57 | +</script> |
| 58 | +``` |
| 59 | + |
| 60 | +You can use reserved words as prop names. |
| 61 | + |
| 62 | +```svelte |
| 63 | +<script> |
| 64 | + // creates a `class` property, even |
| 65 | + // though it is a reserved word |
| 66 | + let { class: className } = $props(); |
| 67 | +</script> |
| 68 | +``` |
| 69 | + |
| 70 | +If you're using TypeScript, you can declare the prop types: |
| 71 | + |
| 72 | +```svelte |
| 73 | +<script lang="ts"> |
| 74 | + interface Props { |
| 75 | + a: number; |
| 76 | + b: boolean; |
| 77 | + c: string; |
| 78 | + [key: string]: unknown; |
| 79 | + } |
| 80 | +
|
| 81 | + let { a, b, c, ...everythingElse }: Props = $props(); |
| 82 | +</script> |
| 83 | +``` |
| 84 | + |
| 85 | +If you export a `const`, `class` or `function`, it is readonly from outside the component. |
| 86 | + |
| 87 | +```svelte |
| 88 | +<script> |
| 89 | + export const thisIs = 'readonly'; |
| 90 | +
|
| 91 | + export function greet(name) { |
| 92 | + alert(`hello ${name}!`); |
| 93 | + } |
| 94 | +</script> |
| 95 | +``` |
| 96 | + |
| 97 | +Readonly props can be accessed as properties on the element, tied to the component using [`bind:this` syntax](/docs/component-directives#bind-this). |
| 98 | + |
| 99 | +### Reactive variables |
| 100 | + |
| 101 | +To change component state and trigger a re-render, just assign to a locally declared variable that was declared using the `$state` rune. |
| 102 | + |
| 103 | +Update expressions (`count += 1`) and property assignments (`obj.x = y`) have the same effect. |
| 104 | + |
| 105 | +```svelte |
| 106 | +<script> |
| 107 | + let count = $state(0); |
| 108 | +
|
| 109 | + function handleClick() { |
| 110 | + // calling this function will trigger an |
| 111 | + // update if the markup references `count` |
| 112 | + count = count + 1; |
| 113 | + } |
| 114 | +</script> |
| 115 | +``` |
| 116 | + |
| 117 | +Svelte's `<script>` blocks are run only when the component is created, so assignments within a `<script>` block are not automatically run again when a prop updates. |
| 118 | + |
| 119 | +```svelte |
| 120 | +<script> |
| 121 | + let { person } = $props(); |
| 122 | + // this will only set `name` on component creation |
| 123 | + // it will not update when `person` does |
| 124 | + let { name } = person; |
| 125 | +</script> |
| 126 | +``` |
| 127 | + |
| 128 | +If you'd like to react to changes to a prop, use the `$derived` or `$effect` runes instead. |
| 129 | + |
| 130 | +```svelte |
| 131 | +<script> |
| 132 | + let count = $state(0); |
| 133 | +
|
| 134 | + let double = $derived(count * 2); |
| 135 | +
|
| 136 | + $effect(() => { |
| 137 | + if (count > 10) { |
| 138 | + alert('Too high!'); |
| 139 | + } |
| 140 | + }); |
| 141 | +</script> |
| 142 | +``` |
| 143 | + |
| 144 | +For more information on reactivity, read the documentation around runes. |
| 145 | + |
| 146 | +## <script context="module"> |
| 147 | + |
| 148 | +A `<script>` tag with a `context="module"` attribute runs once when the module first evaluates, rather than for each component instance. Values declared in this block are accessible from a regular `<script>` (and the component markup) but not vice versa. |
| 149 | + |
| 150 | +You can `export` bindings from this block, and they will become exports of the compiled module. |
| 151 | + |
| 152 | +You cannot `export default`, since the default export is the component itself. |
| 153 | + |
| 154 | +```svelte |
| 155 | +<script context="module"> |
| 156 | + let totalComponents = 0; |
| 157 | +
|
| 158 | + // the export keyword allows this function to imported with e.g. |
| 159 | + // `import Example, { alertTotal } from './Example.svelte'` |
| 160 | + export function alertTotal() { |
| 161 | + alert(totalComponents); |
| 162 | + } |
| 163 | +</script> |
| 164 | +
|
| 165 | +<script> |
| 166 | + totalComponents += 1; |
| 167 | + console.log(`total number of times this component has been created: ${totalComponents}`); |
| 168 | +</script> |
| 169 | +``` |
| 170 | + |
| 171 | +## <style> |
| 172 | + |
| 173 | +CSS inside a `<style>` block will be scoped to that component. |
| 174 | + |
| 175 | +```svelte |
| 176 | +<style> |
| 177 | + p { |
| 178 | + /* this will only affect <p> elements in this component */ |
| 179 | + color: burlywood; |
| 180 | + } |
| 181 | +</style> |
| 182 | +``` |
| 183 | + |
| 184 | +For more information regarding styling, read the documentation around [styles and classes](styles-and-classes). |
0 commit comments