Skip to content

docs(vue): show complete code context in the "Your First App" tutorial #4197

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 22 commits into
base: main
Choose a base branch
from
Open

docs(vue): show complete code context in the "Your First App" tutorial #4197

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
c152d58
docs(vue): add context to code blocks small change to surrounding tex…
soundproofboot Jul 14, 2025
59cef22
docs(vue): add context to code blocks and small changes to surroundin…
soundproofboot Jul 14, 2025
2233653
docs(vue): add context to code blocks and small changes to surroundin…
soundproofboot Jul 14, 2025
6a21dbf
docs(vue): add context to code blocks and small changes to surroundin…
soundproofboot Jul 14, 2025
3635891
docs(vue): add context to code blocks and small changes to surroundin…
soundproofboot Jul 14, 2025
6fb72c4
docs(vue): add context to code blocks and small changes to surroundin…
soundproofboot Jul 16, 2025
bc40cfb
docs(vue): run linter
soundproofboot Jul 16, 2025
1cc3efe
Update docs/vue/your-first-app/3-saving-photos.md
soundproofboot Oct 4, 2025
c29ede6
docs(vue): change name of takePhoto method to addNewToGallery to matc…
soundproofboot Oct 4, 2025
b2926ff
docs(vue): add missing title and head tags to match Angular pages
soundproofboot Oct 4, 2025
c0caf4b
docs(vue): add title to page 7
soundproofboot Oct 4, 2025
05a1aff
Merge branch 'yourFirstAppVue' of https://github.com/soundproofboot/i…
soundproofboot Oct 4, 2025
1907917
docs(vue): update your first app page
thetaPC Oct 22, 2025
e9971d9
docs(vue): update your first app page
thetaPC Oct 22, 2025
6fe3e0a
docs(vue): update your first app page
thetaPC Oct 22, 2025
be5b3a6
docs(vue): update taking photos page
thetaPC Oct 23, 2025
1f92946
docs(vue): update saving photos page
thetaPC Oct 23, 2025
25a2392
docs(vue): update loading photos page
thetaPC Oct 23, 2025
f908015
docs(vue): update adding mobile page
thetaPC Oct 24, 2025
6283f01
docs(vue): update live reload page
thetaPC Oct 24, 2025
32d4b9e
docs(vue): update your first app pages
thetaPC Oct 25, 2025
7663914
docs(vue): update your first app pages
thetaPC Oct 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 103 additions & 57 deletions docs/vue/your-first-app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@ sidebar_label: Build Your First App
---

<head>
<title>Vue Step-by-Step Tutorial: Run Your First Ionic App with Vue</title>
<title>Build Your First Ionic Mobile App: Vue Development Tutorial</title>
<meta
name="description"
content="This Vue tutorial, teaches the fundamentals of Ionic app development by creating a realistic app step-by-step. Learn to run your first Ionic app with Vue."
content="Ionic's single codebase builds for any platform using just HTML, CSS, & JavaScript. Develop your first mobile app with our step-by-step Vue tutorial."
/>
</head>

Expand All @@ -30,9 +30,9 @@ We'll create a Photo Gallery app that offers the ability to take photos with you

Highlights include:

- One Vue-based codebase that runs on the web, iOS, and Android using Ionic Framework [UI components](https://ionicframework.com/docs/components).
- One Vue-based codebase that runs on the web, iOS, and Android using Ionic Framework [UI components](../components.md).
- Deployed as a native iOS and Android mobile app using [Capacitor](https://capacitorjs.com), Ionic's official native app runtime.
- Photo Gallery functionality powered by the Capacitor [Camera](https://capacitorjs.com/docs/apis/camera), [Filesystem](https://capacitorjs.com/docs/apis/filesystem), and [Preferences](https://capacitorjs.com/docs/apis/preferences) APIs.
- Photo Gallery functionality powered by the Capacitor [Camera](../native/camera.md), [Filesystem](../native/filesystem.md), and [Preferences](../native/preferences.md) APIs.

Find the complete app code referenced in this guide [on GitHub](https://github.com/ionic-team/photo-gallery-capacitor-vue).

Expand All @@ -43,9 +43,8 @@ Download and install these right away to ensure an optimal Ionic development exp
- **Node.js** for interacting with the Ionic ecosystem. [Download the LTS version here](https://nodejs.org/en/).
- **A code editor** for... writing code! We are fans of [Visual Studio Code](https://code.visualstudio.com/).
- **Command-line interface/terminal (CLI)**:
- **Windows** users: for the best Ionic experience, we recommend the built-in command line (cmd) or the Powershell
CLI, running in Administrator mode.
- **Mac/Linux** users, virtually any terminal will work.
- **Windows** users: for the best Ionic experience, we recommend the built-in command line (cmd) or the Powershell CLI, running in Administrator mode.
- **Mac/Linux** users: virtually any terminal will work.

## Install Ionic Tooling

Expand All @@ -56,7 +55,7 @@ To open a terminal in Visual Studio Code, go to Terminal -> New Terminal.
:::

```shell
npm install -g @ionic/cli@latest native-run
npm install -g @ionic/cli native-run cordova-res
```

:::note
Expand Down Expand Up @@ -89,29 +88,45 @@ npm install @capacitor/camera @capacitor/preferences @capacitor/filesystem

### PWA Elements

Some Capacitor plugins, including the Camera API, provide the web-based functionality and UI via the Ionic [PWA Elements library](https://github.com/ionic-team/pwa-elements).
Some Capacitor plugins, including the [Camera API](../native/camera.md), provide the web-based functionality and UI via the Ionic [PWA Elements library](https://github.com/ionic-team/pwa-elements).

It's a separate dependency, so install it next:

```shell
npm install @ionic/pwa-elements
```

After installation, open up the project in your code editor of choice.

Next, import `@ionic/pwa-elements` by editing `src/main.ts`.

```tsx
// Above the createApp() line
```ts
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';

import { IonicVue } from '@ionic/vue';
// CHANGE: Add the following import.
import { defineCustomElements } from '@ionic/pwa-elements/loader';

/* Ionic styles are not shown in this example to keep it brief but will be included in the Ionic package downloaded for your app. Do not remove them. */

/* Theme variables */
import './theme/variables.css';

// CHANGE: Call the element loader before the createApp() call
defineCustomElements(window);

const app = createApp(App).use(IonicVue).use(router);

router.isReady().then(() => {
app.mount('#app');
});
```

That’s it! Now for the fun part - let’s see the app in action.

## Run the App

Run this command in your shell:
Run this command next:

```shell
ionic serve
Expand All @@ -121,13 +136,13 @@ And voilà! Your Ionic app is now running in a web browser. Most of your app can

## Photo Gallery!!!

There are three tabs. Click on the Tab2 tab. It’s a blank canvas, aka the perfect spot to transform into a Photo Gallery. The Ionic CLI features Live Reload, so when you make changes and save them, the app is updated immediately!
There are three tabs. Click on the "Tab2" tab. It’s a blank canvas, aka the perfect spot to transform into a Photo Gallery. The Ionic CLI features Live Reload, so when you make changes and save them, the app is updated immediately!

![Animated GIF showing the live reload feature in an Ionic app, with changes in code immediately updating the app in a web browser.](/img/guides/vue/first-app/live-reload.gif 'Live Reload Feature in Ionic App')

Open `/src/views/Tab2.vue`. We see:
Open `/src/views/Tab2Page.vue`. We see:

```html
```vue
<template>
<ion-page>
<ion-header>
Expand All @@ -146,30 +161,53 @@ Open `/src/views/Tab2.vue`. We see:
</ion-content>
</ion-page>
</template>

<script setup lang="ts">
import { IonPage, IonHeader, IonToolbar, IonTitle, IonContent } from '@ionic/vue';
import ExploreContainer from '@/components/ExploreContainer.vue';
</script>
```

`ion-header` represents the top navigation and toolbar, with "Tab 2" as the title. Let’s rename it:
`ion-header` represents the top navigation and toolbar, with "Tab 2" as the title (there are two of them due to iOS [Collapsible Large Title](../api/title.md#collapsible-large-titles) support). Rename both `ion-title` elements to:

```html
```vue
<ion-title>Photo Gallery</ion-title>
```

We put the visual aspects of our app into `<ion-content>`. In this case, it’s where we’ll add a button that opens the device’s camera as well as displays the image captured by the camera. But first, remove the `ExploreContainer` component, beginning with the import statement:
We put the visual aspects of our app into `<ion-content>`. In this case, it’s where we’ll add a button that opens the device’s camera as well as displays the image captured by the camera. Start by adding a [floating action button](../api/fab.md) (FAB) to the bottom of the page and set the camera image as the icon.

```tsx
import ExploreContainer from '@/components/ExploreContainer.vue';
```

Next, remove the `ExploreContainer` node from the HTML markup in the `template`.
```vue
<template>
<ion-page>
<ion-header>
<ion-toolbar>
<ion-title>Photo Gallery</ion-title>
</ion-toolbar>
</ion-header>
<ion-content :fullscreen="true">
<ion-header collapse="condense">
<ion-toolbar>
<ion-title size="large">Photo Gallery</ion-title>
</ion-toolbar>
</ion-header>

```html
<ExploreContainer name="Tab 2 page" />
```
<!-- CHANGE: Add the floating action button. -->
<ion-fab vertical="bottom" horizontal="center" slot="fixed">
<ion-fab-button>
<ion-icon :icon="camera"></ion-icon>
</ion-fab-button>
</ion-fab>

We'll replace it with a [floating action button](https://ionicframework.com/docs/api/fab) (FAB). First, update the imports within the `<script setup>` tag to include the Camera icon as well as some of the Ionic components we'll use shortly:
<!-- CHANGE: Remove or comment out <ExploreContainer /> -->
<!-- <ExploreContainer name="Tab 2 page" /> -->
</ion-content>
</ion-page>
</template>

```tsx
<script setup lang="ts">
// CHANGE: Add import from `ionicons/icons`
import { camera, trash, close } from 'ionicons/icons';
// CHANGE: Update import from `@ionic/vue` to include necessary Ionic components.
import {
IonPage,
IonHeader,
Expand All @@ -184,37 +222,45 @@ import {
IonCol,
IonImg,
} from '@ionic/vue';
// CHANGE: Remove or comment out the ExploreContainer import.
// import ExploreContainer from '@/components/ExploreContainer.vue';
</script>
```

Since our pages are generated as [Vue Single File Components](https://vuejs.org/api/sfc-spec.html) using the [`<script setup>`](https://vuejs.org/api/sfc-script-setup.html#script-setup) syntax these items are now exposed for use in our template.
Next, open `src/views/TabsPage.vue`. Change the label to “Photos” and the `ellipse` icon to `images` for the middle tab button.

Add the FAB to the bottom of the page. Use the camera image as the icon, and call the `takePhoto()` function when this button is clicked (to be implemented soon):

```html
<ion-content :fullscreen="true">
<ion-fab vertical="bottom" horizontal="center" slot="fixed">
<ion-fab-button @click="takePhoto()">
<ion-icon :icon="camera"></ion-icon>
</ion-fab-button>
</ion-fab>
</ion-content>
```

We’ll be creating the `takePhoto` method and the logic to use the Camera and other native features in a moment.

Next, open `src/views/TabsPage.vue`, remove the `ellipse` icon from the import and import the `images` icon instead:
```vue
<template>
<ion-page>
<ion-tabs>
<ion-router-outlet></ion-router-outlet>
<ion-tab-bar slot="bottom">
<ion-tab-button tab="tab1" href="/tabs/tab1">
<ion-icon aria-hidden="true" :icon="triangle" />
<ion-label>Tab 1</ion-label>
</ion-tab-button>

<ion-tab-button tab="tab2" href="/tabs/tab2">
<!-- CHANGE: Update icon. -->
<ion-icon aria-hidden="true" :icon="images" />
<!-- CHANGE: Update label. -->
<ion-label>Photos</ion-label>
</ion-tab-button>

<ion-tab-button tab="tab3" href="/tabs/tab3">
<ion-icon aria-hidden="true" :icon="square" />
<ion-label>Tab 3</ion-label>
</ion-tab-button>
</ion-tab-bar>
</ion-tabs>
</ion-page>
</template>

```tsx
<script setup lang="ts">
import { IonTabBar, IonTabButton, IonTabs, IonLabel, IonIcon, IonPage, IonRouterOutlet } from '@ionic/vue';
// CHANGE: Update import by removing `ellipse` and adding `images`.
import { images, square, triangle } from 'ionicons/icons';
</script>
```

Within the tab bar (`<ion-tab-bar>`), change the label to "Photos" and the `ellipse` icon to `images` for the middle tab button:

```html
<ion-tab-button tab="tab2" href="/tabs/tab2">
<ion-icon :icon="images" />
<ion-label>Photos</ion-label>
</ion-tab-button>
```

That’s just the start of all the cool things we can do with Ionic. Up next, implementing camera taking functionality on the web, then building for iOS and Android.
That’s just the start of all the cool things we can do with Ionic. Up next, implement camera taking functionality on the web, then build it for iOS and Android.
Loading