Skip to content

Latest commit

 

History

History
142 lines (112 loc) · 5.04 KB

theming.md

File metadata and controls

142 lines (112 loc) · 5.04 KB

Prez UI Theming

Quick Start

To get started running your own Prez UI instance, simply run the following to get the starter template, replacing <project_name> with your project name (requires NPM installed, (we recommend pnpm)):

npx create-prez-app@latest <project_name>

(Note: for pnpm, run pnpm dlx instead of npx)

or

npm create prez-app@latest <project_name>

This will download a starter template Nuxt project extending Prez UI's base layer.

In the project root directory, install with your NPM package manager of choice:

npm install

Then preview your theme by running:

npm run dev

Tailwind & CSS

Prez UI uses Tailwind for most of its styling, which you can use in this starter template to easily style using classes.

To override Prez UI's colour scheme (e.g. primary, secondary, etc.), or add your own variables to use in Tailwind, simply add a CSS variable of the same name in assets/css/tailwind.css under :root with its colour values in HSL without the hsl() function, e.g.:

/* assets/css/tailwind.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
    :root {
        /* define your Tailwind CSS variables (in HSL values without the hsl()) here */
        --primary: 24.6 95% 53.1%;
        --primary-foreground: 60 9.1% 97.8%;
    }
}

Then register those variables in tailwind.config.js wrapped in the hsl() function under theme.extend.colors, e.g.:

// tailwind.config.js
module.exports = {
    ...
    theme: {
        extend: {
            colors: {
                // add your CSS variables here, e.g.:
                primary: {
                    DEFAULT: "hsl(var(--primary))",
                    foreground: "hsl(var(--primary-foreground))",
                },
            }
        }
    }
    ...
}

You can also style your Prez UI theme using normal CSS by adding your styles to assets/css/theme.css.

Extending the base layer

This starter template uses Nuxt layers to extend upon the base Prez UI layer application, so you only need to customise what you need.

The layers system automatically replaces files of the same name with the same directory structure as previous layers. The files that can be overridden are:

  • components/* - Extend the default components
  • composables/* - Extend the default composables
  • layouts/* - Extend the default layouts
  • pages/* - Extend the default pages
  • plugins/* - Extend the default plugins
  • server/* - Extend the default server endpoints & middleware
  • utils/* - Extend the default utils
  • nuxt.config.ts - Extend the default nuxt config
  • app.config.ts - Extend the default app config

Refer to Prez UI's base layer source code to help you override files.

The most common case of theming Prez UI is adding a header and footer to every page. This can easily be done by copying & overriding layouts/default.vue from the base layer and replacing the <header> & <footer> elements with your own content.

<!-- layouts/default.vue -->
<template>
    <div class="flex flex-col min-h-screen">

        <!-- Header -->
        <header>
            <!-- your header content here -->
        </header>
        ...
        <!-- Footer -->
        <footer>
            <!-- your footer content here -->
        </footer>
    </div>
</template>

The main navigation can be customised as well in the same file.

Shadcn Components

Prez UI uses the prez-components component library, which is based on the shadcn-vue component library. Shad comes preinstalled in this starter template (badge, button, input & pagination are included as the base layer requires them), but if you need to add more shadcn components in your theme, run a command like the following to add the component:

npx shadcn-vue@latest add button

(Note: for pnpm, run pnpm dlx instead of npx)

These components are stored in components/ui, which should be kept separate to your theme's components.

Other helpful tips

Assets such as images should go in the public/ directory. You can also replace the favicon in this directory by providing your own with the same name and file extension.

nuxt.config.ts contains some useful config for customising your Prez UI theme further. Here you can customise the document title, add external CSS (such as fonts), the base URL, and more. See Nuxt Configuration for more details.

// nuxt.config.ts example
export default defineNuxtConfig({
    ...
    app: {
        head: {
            title: "<document_title>",
            link: [
                { rel: "stylesheet", href: "<stylesheet_url>", type: "text/css" },
            ]
        }
    },
    ...
});