Movie Search App

Search and display movies from an API with loading and error states.

ComposablesFetching DataWatchers

Overview

A movie search app is the project where `watch` really earns its place, because it has to synchronize a component with something outside Vue's control — a network request — every time the user's search term changes. That brings in the exact real-world problems every data-fetching component eventually hits: showing a loading state while a request is pending, showing an error state if it fails, and — trickier — handling the case where the user types fast enough that an *older* request resolves after a *newer* one.

The fetching logic is built as a `useMovieSearch` composable — Vue's equivalent of a custom React hook — so the search-term-to-results pipeline is fully reusable and testable independent of any one component's template. The composable searches the iTunes Search API, a free, no-key, CORS-enabled endpoint that returns real movie data — no account or API key needed, which keeps the focus on Vue instead of authentication setup.

What You'll Build

A controlled search input backed by `ref` and `v-model`.
A `useMovieSearch(query)` composable that fetches movies whenever the query ref changes.
A debounce (via `setTimeout`, cleared on the next change) so a request only fires after the user pauses typing.
Request cancellation with `AbortController` so a slow, stale request can never overwrite fresher results.
`loading`, `error`, and `movies` refs, each driving its own conditionally-rendered piece of UI.
A responsive grid of movie cards built from the live API response.

Prerequisites

Template syntax, Single File Components, and `ref` — covered in the Todo App project above.
Promises and `async`/`await`, and `try`/`catch` error handling.
The Fetch API — calling `fetch(url)` and reading a `Response` with `.json()`.
Conditional rendering with `v-if`/`v-else-if`/`v-else`.
`watch`, composables, and `AbortController` are new here — every one is introduced from scratch in this tutorial.

Project Structure

All of the interesting logic — when the fetch happens, and what the four possible outcomes (idle, loading, error, results) look like — lives in one composable, which keeps `App` itself small: it just owns the `query` ref, calls `useMovieSearch(query)`, and renders whatever comes back.

src/
  composables/
    useMovieSearch.js  // Debounced, cancellable fetch logic — the reusable core of the project
  App.vue              // Search input + conditional rendering, driven entirely by the composable
  style.css             // Shared dark-theme styling

* { box-sizing: border-box; margin: 0; padding: 0; }

body {
  font-family: Arial, Helvetica, sans-serif;
  background: #1a1d23;
  color: #e8e8e8;
  display: flex;
  justify-content: center;
  padding: 40px 16px;
}

.movie-app { width: 100%; max-width: 640px; }
.movie-app h1 { margin-bottom: 16px; font-size: 1.5rem; }

.movie-app input {
  width: 100%;
  padding: 10px 12px;
  border-radius: 6px;
  border: 1px solid #3a3f4b;
  background: #23262e;
  color: #e8e8e8;
  font-size: 1rem;
  margin-bottom: 16px;
}

.status { color: #9aa4b2; padding: 12px 0; }
.status.error { color: #ff6b6b; }

.movie-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(120px, 1fr));
  gap: 14px;
}

.movie-card { background: #23262e; border-radius: 8px; overflow: hidden; }
.movie-card img { width: 100%; display: block; }
.movie-card h3 { font-size: 0.85rem; padding: 8px 8px 2px; }
.movie-card p { font-size: 0.75rem; color: #9aa4b2; padding: 0 8px 8px; }

Step 1: Set Up State and a Controlled Search Input

`query` is the one piece of state `App` owns directly — everything else (`movies`, `loading`, `error`) is going to come back from the composable in Step 2. `v-model` keeps `query` and the input's visible text permanently in sync.

<!-- App.vue -->
<script setup>
import { ref } from 'vue';

const query = ref(''); // exactly what's currently typed in the search box
</script>

<template>
  <div class="movie-app">
    <h1>Movie Search</h1>
    <input
      v-model="query"
      type="text"
      placeholder="Search for a movie..."
    />
    <!-- Loading / error / results rendering is added in Steps 5 and 6 -->
  </div>
</template>

Step 2: Build the useMovieSearch Composable

A composable takes reactive input (here, the `query` ref itself, not its unwrapped value) and returns reactive output — `App` will call `useMovieSearch(query)` and get back `movies`/`loading`/`error` refs whose values update automatically. Passing the ref itself (not `query.value`) is what lets the composable set up its own `watch` internally.

// composables/useMovieSearch.js
import { ref, watch } from 'vue';

export function useMovieSearch(query) {
  const movies = ref([]);
  const loading = ref(false);
  const error = ref(null);

  // watch(query, ...) re-runs this callback every time query.value changes —
  // v-model on the input in App.vue is what drives those changes
  watch(query, (newQuery) => {
    if (newQuery.trim() === '') {
      movies.value = [];
      error.value = null;
      return;
    }

    async function fetchMovies() {
      loading.value = true;
      error.value = null;

      try {
        const url =
          'https://itunes.apple.com/search?media=movie&limit=12&term=' +
          encodeURIComponent(newQuery); // encodeURIComponent safely escapes spaces/punctuation in the search term
        const response = await fetch(url);

        if (!response.ok) {
          throw new Error('Search request failed.');
        }

        const data = await response.json();
        movies.value = data.results;
      } catch (err) {
        error.value = err.message;
        movies.value = [];
      } finally {
        loading.value = false; // runs whether the request succeeded or failed
      }
    }

    fetchMovies();
  });

  // The composable hands back reactive refs — App.vue reads these the same
  // way it would read its own local ref() state
  return { movies, loading, error };
}

This version works, but it fires a network request on every single keystroke — typing "batman" triggers six separate searches for "b", "ba", "bat", and so on. The next two steps fix that.

Step 3: Debounce the Search Inside the Watcher

A debounce waits for a pause in typing before actually doing the work. Because the previous version's `watch` callback ran the fetch immediately, a variable declared *outside* the callback (so it survives between calls) is needed to hold the pending timer — each new call to the callback clears whatever the last one scheduled before starting its own, which is exactly what turns a delay into a debounce.

// composables/useMovieSearch.js (debounced)
import { ref, watch } from 'vue';

export function useMovieSearch(query) {
  const movies = ref([]);
  const loading = ref(false);
  const error = ref(null);

  // Declared outside the watch callback so it persists across calls —
  // each new keystroke can see and clear the PREVIOUS keystroke's timer
  let timeoutId = null;

  watch(query, (newQuery) => {
    if (timeoutId) clearTimeout(timeoutId); // cancel whatever the previous keystroke scheduled

    if (newQuery.trim() === '') {
      movies.value = [];
      error.value = null;
      return;
    }

    // Wait 400ms after the last keystroke before actually searching
    timeoutId = setTimeout(async () => {
      loading.value = true;
      error.value = null;
      try {
        const url =
          'https://itunes.apple.com/search?media=movie&limit=12&term=' +
          encodeURIComponent(newQuery);
        const response = await fetch(url);
        if (!response.ok) throw new Error('Search request failed.');
        const data = await response.json();
        movies.value = data.results;
      } catch (err) {
        error.value = err.message;
        movies.value = [];
      } finally {
        loading.value = false;
      }
    }, 400);
  });

  return { movies, loading, error };
}

Step 4: Cancel Stale Requests with AbortController

Debouncing controls when a request *starts*, but a slow network can still let an older request *finish* after a newer one — searching "cat" then quickly "car" could, without this step, show "cat" results last if that request happens to resolve second. `AbortController`, tracked the same way `timeoutId` is, lets the next keystroke cancel the in-flight request itself, not just the timer that was going to start it.

// composables/useMovieSearch.js (final)
import { ref, watch } from 'vue';

export function useMovieSearch(query) {
  const movies = ref([]);
  const loading = ref(false);
  const error = ref(null);

  let timeoutId = null;
  let controller = null; // tracks the AbortController for the most recent request

  watch(query, (newQuery) => {
    if (timeoutId) clearTimeout(timeoutId);
    if (controller) controller.abort(); // cancel a still-in-flight request from an older, now-stale search term

    if (newQuery.trim() === '') {
      movies.value = [];
      error.value = null;
      return;
    }

    timeoutId = setTimeout(async () => {
      controller = new AbortController(); // a fresh controller tied to THIS specific request
      loading.value = true;
      error.value = null;

      try {
        const url =
          'https://itunes.apple.com/search?media=movie&limit=12&term=' +
          encodeURIComponent(newQuery);
        const response = await fetch(url, { signal: controller.signal }); // ties this fetch to the controller so it can be aborted

        if (!response.ok) throw new Error('Search request failed.');

        const data = await response.json();
        movies.value = data.results;
      } catch (err) {
        // A cancelled fetch rejects with an AbortError — that's expected
        // behavior from the debounce, not a real failure, so it's
        // deliberately NOT shown to the user as an error
        if (err.name !== 'AbortError') {
          error.value = err.message;
          movies.value = [];
        }
      } finally {
        loading.value = false;
      }
    }, 400);
  });

  return { movies, loading, error };
}

Step 5: Render Loading, Error, and Empty States

Each of the four states — loading, error, no-results, and idle — is checked with `v-if`/`v-else-if`/`v-else`, so exactly one of them ever renders at a time.

<template>
  <p v-if="loading" class="status">Loading...</p>
  <p v-else-if="error" class="status error">{{ error }}</p>
  <p v-else-if="query.trim() !== '' && movies.length === 0" class="status">
    No movies found for "{{ query }}".
  </p>
</template>

Step 6: Render the Movie Grid

Once `movies` has results, `v-for` turns each one into a card. The iTunes API returns `trackId` (a stable unique id), `trackName`, `artworkUrl100` (a small poster image), and `releaseDate` as an ISO string — `.slice(0, 4)` pulls just the year out of it for display.

<template>
  <div class="movie-grid">
    <div class="movie-card" v-for="movie in movies" :key="movie.trackId">
      <img :src="movie.artworkUrl100" :alt="movie.trackName" />
      <h3>{{ movie.trackName }}</h3>
      <p>{{ movie.releaseDate ? movie.releaseDate.slice(0, 4) : 'Unknown year' }}</p>
    </div>
  </div>
</template>

Complete Code

Here is the complete project, using the real iTunes Search API exactly as you would call it from a live page.

* { box-sizing: border-box; margin: 0; padding: 0; }

body { font-family: Arial, Helvetica, sans-serif; background: #1a1d23; color: #e8e8e8; display: flex; justify-content: center; padding: 40px 16px; }
.movie-app { width: 100%; max-width: 640px; }
.movie-app h1 { margin-bottom: 16px; font-size: 1.5rem; }
.movie-app input { width: 100%; padding: 10px 12px; border-radius: 6px; border: 1px solid #3a3f4b; background: #23262e; color: #e8e8e8; font-size: 1rem; margin-bottom: 16px; }
.status { color: #9aa4b2; padding: 12px 0; }
.status.error { color: #ff6b6b; }
.movie-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(120px, 1fr)); gap: 14px; }
.movie-card { background: #23262e; border-radius: 8px; overflow: hidden; }
.movie-card img { width: 100%; display: block; }
.movie-card h3 { font-size: 0.85rem; padding: 8px 8px 2px; }
.movie-card p { font-size: 0.75rem; color: #9aa4b2; padding: 0 8px 8px; }

// composables/useMovieSearch.js
import { ref, watch } from 'vue';

export function useMovieSearch(query) {
  const movies = ref([]);
  const loading = ref(false);
  const error = ref(null);

  let timeoutId = null;
  let controller = null;

  watch(query, (newQuery) => {
    if (timeoutId) clearTimeout(timeoutId);
    if (controller) controller.abort();

    if (newQuery.trim() === '') {
      movies.value = [];
      error.value = null;
      return;
    }

    timeoutId = setTimeout(async () => {
      controller = new AbortController();
      loading.value = true;
      error.value = null;

      try {
        const url =
          'https://itunes.apple.com/search?media=movie&limit=12&term=' +
          encodeURIComponent(newQuery);
        const response = await fetch(url, { signal: controller.signal });
        if (!response.ok) throw new Error('Search request failed.');
        const data = await response.json();
        movies.value = data.results;
      } catch (err) {
        if (err.name !== 'AbortError') {
          error.value = err.message;
          movies.value = [];
        }
      } finally {
        loading.value = false;
      }
    }, 400);
  });

  return { movies, loading, error };
}

<!-- App.vue -->
<script setup>
import { ref } from 'vue';
import { useMovieSearch } from './composables/useMovieSearch';

const query = ref('');
const { movies, loading, error } = useMovieSearch(query);
</script>

<template>
  <div class="movie-app">
    <h1>Movie Search</h1>
    <input v-model="query" type="text" placeholder="Search for a movie..." />

    <p v-if="loading" class="status">Loading...</p>
    <p v-else-if="error" class="status error">{{ error }}</p>
    <p v-else-if="query.trim() !== '' && movies.length === 0" class="status">
      No movies found for "{{ query }}".
    </p>

    <div class="movie-grid">
      <div class="movie-card" v-for="movie in movies" :key="movie.trackId">
        <img :src="movie.artworkUrl100" :alt="movie.trackName" />
        <h3>{{ movie.trackName }}</h3>
        <p>{{ movie.releaseDate ? movie.releaseDate.slice(0, 4) : 'Unknown year' }}</p>
      </div>
    </div>
  </div>
</template>

The live preview below cannot reliably reach an external API from inside a sandboxed iframe, so it swaps the real `fetch` call for a small local dataset and a simulated delay — everything else (the composable shape, the debounce, the loading/error/empty states, the grid) behaves identically to the real, network-connected version above.

Sample Run

Sample Interaction

Click Run to see what this code prints.

Extend This Project

Add a "Load More" button that requests the next page of results and appends them to `movies.value`.
Add a genre or media-type dropdown (movie / tv show / music) that becomes part of the query string.
Click a card to open a detail view with the movie's longer description, fetched from a second endpoint.
Save searched movies to a "favorites" list in `localStorage`, reusing the persistence pattern from the Todo App project.
Cache recent search results in a plain (non-reactive) `Map` inside the composable so re-searching the same term shows results instantly without a new request.

Summary

You built a real, network-connected search feature packaged as a `useMovieSearch` composable, using `watch` to synchronize component state with an external API, a manually-tracked timer to debounce rapid input, and `AbortController` to prevent stale responses from overwriting fresh ones. This exact shape — a composable wrapping debounce, abort-on-next-change, and loading/error/empty state — is the pattern you will reach for in almost any Vue component that searches or fetches data as the user types.