Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 87 ยท Getting Started

Single-File Components

Learn the anatomy of a Vue single-file component (template, script setup, scoped style), how a .vue file compiles, and a runnable equivalent in plain HTML.

A single-file component (SFC) is a file ending in .vue that keeps everything about one piece of UI together: its markup, its logic and its styles. Instead of hunting through an HTML file, a JavaScript file and a CSS file when a button misbehaves, you open one file named after the component. SFCs are the normal way to write Vue in real projects.

Browsers cannot read .vue files, and the live editors on this site cannot compile them, so this lesson shows SFCs as read-only code and then gives you a runnable equivalent for each one. By the end you will be able to read any .vue file, and translate it to the template-string style used in this tutorial and back.

The anatomy of a .vue file

A typical SFC has three blocks:

HTML
<script setup>
import { ref } from "vue";

const count = ref(0);
function increment() {
  count.value++;
}
</script>

<template>
  <button class="counter" type="button" @click="increment">
    Clicked {{ count }} times
  </button>
</template>

<style scoped>
.counter {
  padding: 0.5rem 1rem;
  border-radius: 6px;
}
</style>
  • <template> holds the markup, with the same syntax you have already used in template strings. Only one <template> block is allowed per file.
  • <script setup> holds the logic. It is the compact form of setup(): every top-level variable, function and import is automatically available in the template, so there is no return { ... } list. You will meet it in detail in Composition API and script setup.
  • <style scoped> holds CSS that applies only to this component (more on that below). You may also write a plain <style> for global rules, or use several style blocks.

The order of the blocks does not matter to Vue. Many teams put <script setup> first, then <template>, then <style>, and the official style guide asks you to keep one order across a project.

What the compiler does

A .vue file is not valid JavaScript, so a build tool must transform it. In a Vite project, the official Vue plugin runs the SFC compiler, which splits the file into its blocks and compiles each one:

flowchart LR
    F["Counter.vue"] --> C["SFC compiler<br/>(Vite plugin)"]
    C --> S["script setup<br/>becomes a setup() function"]
    C --> T["template<br/>becomes a render function"]
    C --> Y["style scoped<br/>becomes CSS with attribute selectors"]
    S --> M["One JavaScript module<br/>exporting a component object"]
    T --> M
    Y --> W["CSS file or style tag"]

The browser never sees .vue syntax. It receives a normal JavaScript module and a stylesheet.

The compiled result is, very roughly, the same component object you wrote by hand in the previous lessons:

JavaScript
// a simplified picture of the output, not the exact generated code
export default {
  setup() {
    const count = ref(0);
    function increment() { count.value++; }
    return { count, increment };
  },
  render(ctx) {
    // creates a <button> vnode with the text "Clicked N times"
  },
};

Because the template is turned into a render function at build time, nothing has to parse template text in the user's browser. That is why SFC projects ship the smaller "runtime-only" build of Vue.

The same component, runnable

To run the component above on this site, we replace the file with an object: the <template> becomes the template string, <script setup> becomes setup() with a return, and the <style> becomes a normal <style> element on the page:

The Counter component without a .vue file

The logic and the markup are the same line for line. What you lose without a build step is the file separation, editor checking inside strings and style isolation. The next section shows what scoped styles actually do.

How scoped styles work

Plain CSS is global: a rule for .title styles every .title on the page, in any component. <style scoped> avoids that. The compiler gives each component a random id and does two things:

  1. It adds an attribute such as data-v-7ba5bd90 to every element rendered by this component's template.
  2. It rewrites each selector in the style block so that it also requires that attribute: .title becomes .title[data-v-7ba5bd90].

Since no other component's elements carry that attribute, the rule cannot leak out. You can reproduce the mechanism by hand to see that there is no magic:

Scoping is an attribute selector

Only the first heading is red. Both have the class title, but only the first one has the attribute that the rewritten selector requires. Scoped styles get their own lesson, Scoped CSS and CSS Modules, including how to style child components and slot content.

Using one SFC inside another

In a project, you import a component and use it in the template of its parent. With <script setup>, an imported component can be used straight away:

HTML
<script setup>
import UserCard from "./UserCard.vue";
</script>

<template>
  <UserCard name="Ada" />
  <UserCard name="Grace" />
</template>

The runnable equivalent registers the component in a components option, which is what the build tool generates for you. A more detailed treatment follows in Components Basics.

Parent and child components

Inside a string template that the browser's compiler reads, <user-card> (kebab-case, with a closing tag) matches the registered UserCard. In an SFC you can write either <UserCard /> or <user-card />.

Tips for working with SFCs

  • Install the Vue - Official extension in your editor for highlighting, completions and error checking inside all three blocks.
  • Name files in PascalCase (UserCard.vue) and keep one component per file.
  • Keep SFCs short. When a template gets long or the script mixes unrelated jobs, split it into smaller components.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What are the three blocks of a typical single-file component?

    A .vue file holds a template block, a script block and a style block, so one component's markup, logic and styles live together.
  2. 2. Why can't a browser run a .vue file directly?

    The SFC compiler splits the blocks and converts them into a component module, a render function and CSS before the browser sees anything.
  3. 3. What does <style scoped> do to a selector like .title?

    Scoping adds a data-v-xxxx attribute to the component's elements and requires it in the selector, so the style cannot leak to other components.
  4. 4. In <script setup>, how do you expose a variable or imported component to the template?

    script setup is a compile-time shorthand for setup(): its top-level variables, functions and imports can be used in the template without a return object.

Summary

  • A .vue single-file component keeps a component's <template>, <script setup> and <style> in one file.
  • A build step compiles the file into a normal JavaScript module with a render function, plus CSS; the browser never reads .vue syntax.
  • <script setup> exposes all top-level bindings to the template without a return.
  • scoped styles work by adding a generated data-v- attribute to elements and to the selectors.
  • Every SFC has a runnable equivalent: the template as a template string, the script as setup(), the style as a <style> element.

Next: Text Interpolation