Intro Navify React Quickstart
What is Navify Framework?
First off, if you're new here, welcome! Navify is a free and open source component library for building apps that run on iOS, Android, Electron, and the Web. You write your app once using familiar technologies (HTML, CSS, JavaScript) and deploy to any platform.
Along with the UI components, Navify also provides a command line tool for creating new apps, as well as deploying to the various platforms we support.
In this guide, we'll go over the basics of both React and Navify, including any Navify specific features. If you're familiar with React, enjoy the guide and learn something new about Navify. If you're not familiar with either, no worries! This guide will cover the basics and provide enough information to get an app up and running.
Creating a project with the Navify CLI
To begin, let's install the latest version of the Navify CLI.
npm install -g @navify/cli
From here, the global command navify
will allow for the creation of a React project with Navify and any other dependencies. To create a new project, run the following command:
navify start myApp blank --type=react
cd myApp
From here, we run navify serve
and have our project running in the browser.
A look at a React Component
The base of our app will be in the src
directory, and the main entry point will be our index.tsx
. If we open our project in a code editor and open src/index.tsx
, we should see the following:
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
ReactDOM.render(<App />, document.getElementById('root'));
So what's going on here? Well, the first three lines are pulling in some dependencies. The first being React itself. This allows us to write components in an HTML-like syntax called JSX. We'll talk about JSX a bit later on.
The second import is for ReactDOM. The ReactDOM.render
method is the browser/DOM specific way of taking our components and rendering it to a specified DOM node.
The last import is the root component for our app, simply named App
. This is our first React component and will be used in the bootstrapping process for our React app.
If we open App.tsx
, we should see the following.
import React from 'react';
import { Route } from 'react-router-dom';
import { NavApp, NavRouterOutlet } from '@navify/react';
import { NavReactRouter } from '@navify/react-router';
import Home from './pages/Home';
/* Core CSS required for Navify components to work properly */
import '@navify/react/css/core.css';
const App: React.FC = () => (
<NavApp>
<NavReactRouter>
<NavRouterOutlet>
<Route path="/home" component={Home} exact={true} />
<Route exact path="/" render={() => <Redirect to="/home" />} />
</NavRouterOutlet>
</NavReactRouter>
</NavApp>
);
At first glance, it may look like a lot is going on, so let's break it down, starting with the first group of imports.
import React from 'react';
import { Route } from 'react-router-dom';
import { NavApp, NavRouterOutlet } from '@navify/react';
import { NavReactRouter } from '@navify/react-router';
import Home from './pages/Home';
Similar to index.tsx
, we first must import React to use JSX.
The next import is from react-router-dom
. We're importing Route, which is how we’ll match the app’s URL with the components we want to render
Following ReactRouter, we next have our first imports for Navify. To use a component in React, you must first import it. So for Navify, this means anytime we want to use a Button or a Card, it must be added to our imports. In the case of our App component, we're only using NavApp
, NavRouterOutlet
, and NavReactRouter
.
NavReactRouter
is a component that wraps ReactRouter’s BrowserRouter component. It more or less behaves the same as BrowserRouter with a few differences. We have a deeper guide that goes over these differences in our React Navigation Docs.
The last important import is the Home
component import. This is a component that we will be able to navigate to in our app. We'll look at the navigation part a bit later.
The CSS import is pulling in the utility styles from Navify for things like padding, typography, etc.
After reviewing all of the imports, we now get to our first look at a React Component:
const App: React.FC = () => (
<NavApp>
<NavReactRouter>
<NavRouterOutlet>
<Route path="/home" component={Home} exact={true} />
<Route exact path="/" render={() => <Redirect to="/home" />} />
</NavRouterOutlet>
</NavReactRouter>
</NavApp>
);
This React component sets up the initial routing for our app, as well as include some core Navify components for animations and layout (NavRouterOutlet and NavApp). One thing that stands out is that in React, to do data-binding, the value is passed in curly braces ({}
). So in the Route
component, we can set the value of component
to the Home
component from earlier. This is how React will know that that value is not a string, but a reference to a component.
note
What's important to note here is that these are all standard React DOM libraries, meaning there's no custom integration layer or transpilation step.
A component with style
Now the App
does not really have a lot to modify here. It's a basic example of a container component. With the Router logic set, all it's responsible for is to render a component that matches the given URL route. Since we already have one component/router setup, let's go ahead and modify our Home
component.
import { NavContent, NavHeader, NavPage, NavTitle, NavToolbar } from '@navify/react';
import React from 'react';
const Home: React.FC = () => {
return (
<NavPage>
<NavHeader>
<NavToolbar>
<NavTitle>Navify Blank</NavTitle>
</NavToolbar>
</NavHeader>
<NavContent className="nav-padding">
The world is your oyster.
<p>
If you get lost, the{' '}
<a target="_blank" rel="noopener" href="https://navifyframework.web.app/docs/">
docs
</a>{' '}
will be your guide.
</p>
</NavContent>
</NavPage>
);
};
Much like the App
component we started with, we have some imports for specific Navify components, an import for React, and then our React component itself.
NavPage
is the base component for all pages (a component with a route/URL), and includes some common building blocks of a full-screen component, like header, title, and content components.
note
When creating your own pages, don't forget to have NavPage
be the root component for them. Having NavPage
be the root component is important because it helps ensure transitions work properly as well as provides the base CSS the Navify components rely on.
NavHeader
is a bit self explanatory. It's a component that is meant to exist at the top of the page. NavHeader
itself doesn't do much by itself, aside from handling some flexbox-based layout. It's meant to hold other components, like NavToolbar
or NavSearchbar
.
NavContent
is, as its name suggests, the main content area for our page. It's responsible for providing the scrollable content that users will interact with, plus any scroll events that could be used in an app.
Our current content is relatively simple but does not contain anything that could be used in a real app, so let's change that.
note
For brevity, we're excluding repeating part of our component, like the function declaration or import statements for other components.
<NavPage>
...
<NavContent>
<NavList>
<NavItem>
<NavCheckbox slot="start" />
<NavLabel>
<h1>Create Idea</h1>
<NavNote>Run Idea by Brandy</NavNote>
</NavLabel>
<NavBadge color="success" slot="end">
5 Days
</NavBadge>
</NavItem>
</NavList>
</NavContent>
</NavPage>
Here in our NavContent
, we're adding an NavList
and a much more involved NavItem
component. Let's look at NavItem
, as it's the centerpiece here.
<NavItem>
<NavCheckbox slot="start" />
<NavLabel>
<h1>Create Idea</h1>
<NavNote>Run Idea by Brandy</NavNote>
</NavLabel>
<NavBadge color="success" slot="end">
5 Days
</NavBadge>
</NavItem>
Item is important as it clearly shows the mix of React concepts and Web Component concepts. The first clear example of a React concept is self-closing tags for React Components in NavCheckbox
. This is just a simpler way of writing components that do not contain any child content.
From the Web Components side, we have a special attribute called slot
. This is key for letting the NavItem
know where to place the NavCheckbox
when it renders. This is not a React API, but a web standards API.
Let's look at another component from Navify, FAB. Floating Action Buttons are a nice way to provide a main action that is elevated from the rest of an app. For this FAB, we'll need three components: a FAB, a FAB Button, and an Icon.
import { add } from ‘navicons/icons’;
…
<NavContent>
<NavList>
...
</NavList>
<NavFab vertical="bottom" horizontal="end" slot="fixed">
<NavFabButton>
<NavIcon icon={add} />
</NavFabButton>
</NavFab>
</NavContent>
On our main NavFab
, we're setting its positioning with the vertical and horizontal attributes. We're also setting the render location to "fixed" with the slot attribute. This will tell NavFab
to render outside of the scrollable content in NavContent
.
Now let's wire up a click handler to this. What we want to do is when we click the button, we'll navigate to a new page (which we'll create in a moment). To do this, we'll need to get access to React Router's navigation API. Thankfully since this is rendered in a Router/Route context, we have access to React Routers APIs via Props passed to our Home component.
import { add } from 'navicons/icons';
...
const Home: React.FC<RouteComponentProps> = (props) => {
return (
<NavPage>
<NavHeader>...</NavHeader>
<NavContent>
<NavList>...</NavList>
<NavFab vertical="bottom" horizontal="end" slot="fixed">
<NavFabButton onClick={() => props.history.push('/new')}>
<NavIcon icon={add} />
</NavFabButton>
</NavFab>
</NavContent>
</NavPage>
);
}
export default Home;
In our component declaration, we're passing in props
which is of type RouteComponentProps
(imported from react-router
). This props
object gives us access to the history API from React Router, allowing us to push a new route onto the navigation stack. On our NavFabButton
, we can add a click handler, and just call props.history.push
and pass in the new route. In this case, we'll navigate to new
.
<NavFabButton onClick={() => props.history.push('/new')} >
Creating a new Route
Now that we have the pieces in place to navigate in our app, we need to create a new component and add the new route to our router declaration. Let's open our App.tsx
file and add the new route.
...
import Home from './pages/Home';
import NewItem from './pages/NewItem';
...
const App: React.FC = () => {
const isAuthed = true;
return (
<NavApp>
<NavReactRouter>
<NavRouterOutlet>
<Route path="/home" component={Home} />
<Route path="/new" component={NewItem} />
<Redirect exact from="/" to="/home" />
</NavRouterOutlet>
</NavReactRouter>
</NavApp>
);
}
export default App;
With our router now having an entry for the route /new
, we'll create the component needed, NewItem
. This will exist in src/pages/NewItem.tsx
Let's fill the NewItem.tsx
with some placeholder content for the moment.
import { NavBackButton, NavButtons, NavContent, NavHeader, NavPage, NavTitle, NavToolbar } from '@navify/react';
import React from 'react';
const NewItem: React.FC = () => {
return (
<NavPage>
<NavHeader>
<NavToolbar>
<NavButtons slot="start">
<NavBackButton />
</NavButtons>
<NavTitle>New Item</NavTitle>
</NavToolbar>
</NavHeader>
<NavContent></NavContent>
</NavPage>
);
};
export default NewItem;
note
Each view must contain an NavPage
component. Page transitions will not work correctly without it. See the NavPage Documentation for more information.
The content here is pretty straight forward and should look similar to the Home
component. What is new is the NavBackButton
component. This is used to navigate back to the previous route. Pretty straight forward? Ok, but what if we reload the page?
Well, in this case, the in-memory history is lost, so the back button disappears. To address this, we can set the defaultHref
attribute value to the URL we want to navigate to if there is no history.
return (
<NavPage>
<NavHeader>
<NavToolbar>
<NavButtons slot="start">
<NavBackButton defaultHref="/home" />
</NavButtons>
<NavTitle>New Item</NavTitle>
</NavToolbar>
</NavHeader>
<NavContent />
</NavPage>
);
Here, when we reload, if there is no app history present, we'll be able to navigate back to our home route.
Adding Icons
Navify React comes with (https://navify.web.app/navicons/) pre-installed. All you need to do is import the icon of your choice from the navicons
package, and pass it to an NavIcon
component through the icon
prop:
import React from 'react';
import { NavButton, NavContent, NavIcon } from '@navify/react';
import { camera } from 'navicons/icons';
export const IconExample: React.FC = () => {
<NavContent>
<NavButton>
<NavIcon icon={camera} />
Take Picture
</NavButton>
</NavContent>;
};
Note that for React, we are passing the imported SVG reference, not the icon name as a string.
Developers also have the option of setting different icons based upon the mode:
import React from 'react';
import { NavButton, NavContent, NavIcon } from '@navify/react';
import { logoAndroid, logoApple } from 'navicons/icons';
export const IconExample: React.FC = () => {
<NavContent>
<NavButton>
<NavIcon ios={logoApple} md={logoAndroid} />
</NavButton>
</NavContent>;
};
Build a Native App
We now have the basics of an Navify React app down, including some UI components and navigation. The great thing about Navify’s components is that they work anywhere, including iOS, Android, and PWAs. To deploy to mobile, desktop, and beyond, we use Navify’s cross-platform app runtime Jigra. It provides a consistent, web-focused set of APIs that enable an app to stay as close to web-standards as possible while accessing rich native device features on platforms that support them.
Adding native functionality is easy. First, add Jigra to your project:
navify integrations enable jigra
Next, build the project, then add your platform of choice:
navify build
navify jig add ios
navify jig add android
We use the standard native IDEs (Xcode and Android Studio) to open, build, and run the iOS and Android projects:
navify jig open ios
navify jig open android
Additional details can be found here.
Next, check out all the APIs that are available. There’s some great stuff, including the Camera API. We can implement photo capture functionality in just a few lines of code:
import { NavContent, NavHeader, NavPage, NavTitle, NavToolbar, NavButton } from '@navify/react';
import React, { useState } from 'react';
import { Plugins, CameraResultType } from '@jigra/core';
const Home: React.FC = () => {
const { Camera } = Plugins;
const [photo, setPhoto] = useState();
const takePhoto = async () => {
const image = await Camera.getPhoto({
quality: 90,
allowEditing: true,
resultType: CameraResultType.Uri,
});
setPhoto(image.webPath);
};
return (
<NavPage>
<NavHeader>
<NavToolbar>
<NavTitle>Navify Blank</NavTitle>
</NavToolbar>
</NavHeader>
<NavContent className="nav-padding">
<img src={photo} />
<NavButton onClick={takePhoto}>Take Photo</NavButton>
</NavContent>
</NavPage>
);
};
export default Home;
Where to go from here
This guide covered the basics of creating an Navify React app, adding some basic navigation, and introducing Jigra as a way of building native apps. To dive deeper into building complete Navify apps with React and Jigra, follow our First App guide.
For a more detailed look at Navify’s components, check out the component API pages. For more details on React, review the React Docs. To keep building native features, see the Jigra docs.
Happy app building! 🎉