DEV Community: Prismane

Custom Components with Prismane

Prismane — Fri, 15 Dec 2023 21:38:29 +0000

Hello, and welcome to our tutorial on creating custom components with Prismane.

In this guide, we will explore the process of building custom components that not only enhance the visual appeal of your UI but also provide a higher degree of versatility and reusability in your projects.

Feel free to explore the code examples provided throughout this tutorial, which are conveniently hosted on our GitHub Repository.

Prerequisites

Before we delve into building custom components with Prismane, it's essential to have a basic understanding of Prismane and its fundamental concepts. If you're new to Prismane, here are some resources to help you get started:

Installation Guide:
- Make sure you have Prismane installed in your project. Follow the installation guide in the official Prismane documentation.
Introduction to Prismane:
- Familiarize yourself with the core concepts of Prismane. The Prismane documentation provides a comprehensive introduction to its features and usage.
Prismane Core Concepts:
- Have a grasp of key styling concepts. Refer to the Styling section for a deeper understanding.

Initial Component

Start by creating a new component called StyledButton. This code creates an unstyled button component that we are going to use as a base on which we are going to build further into the tutorial.

import React, { HTMLAttributes } from "react";

const StyledButton = ({ children, ...props }: HTMLAttributes<HTMLElement>) => {
  return <button {...props}>{children}</button>;
};

export default StyledButton;

Prop Types in Prismane

In Prismane, the prop types for each component are conveniently exposed for developers to reference and utilize. These prop types can be imported directly from the @prismane/core root entry point, making it straightforward to explore and understand the expected properties for each component.

Prop Types Naming Convention

Prismane follows a structured naming convention for prop types. The pattern is as follows:

{ComponentName}Props

Therefore, if you are working with the Button component, its prop types will be named ButtonProps.

By adhering to this straightforward naming convention, Prismane makes it easy for developers to locate and utilize the prop types associated with each component. This ensures clarity and consistency when working with the diverse set of components provided by Prismane.

Accessing Prop Types

To access the prop types, import them using the following structure:

// Importing ButtonProps as an example
import { ButtonProps } from '@prismane/core';

Replace Button with the name of the specific component you are interested in. This simple import grants you access to the prop types associated with the chosen component.

Custom Button Component

In this section, we'll explore the creation of custom components by extending and styling the existing Prismane Button component. This approach ensures consistency with the overall design system while allowing for customization when needed.

Understanding the Prismane Button Component

Before creating a custom component, familiarize yourself with the
Prismane Button and its styling. The official Prismane documentation on Buttons provides insights into the default styles and available variations.

Integrating the Button Component from Prismane

To integrate the Button component, we will need to replace the button element with the Button component that we will import from @prismane/core and change the prop types to the ButtonProps .

import { Button, ButtonProps } from "@prismane/core";

const StyledButton = ({ children, ...props }: ButtonProps) => {
  return <Button {...props}>{children}</Button>;
};

export default StyledButton;

Using the StyledButton Component

Now, you can use PrimaryButton wherever you need a consistent styled button:

import StyledButton from "./components/StyledButton";

function App() {
  return <StyledButton>Custom Button</StyledButton>;
}

export default App;

This will result in:

This allows for seamless integration of your custom button while maintaining the benefits of the Prismane styling system.

Styling the new StyledButton Component

After integrating the Button component from Prismane and it’s prop types, now we can use all of the props that Button supports.

import { Button, ButtonProps } from "@prismane/core";

const StyledButton = ({ children, ...props }: ButtonProps) => {
  return (
    <Button variant="secondary" color="teal" br="full" {...props}>
      {children}
    </Button>
  );
};

export default StyledButton;

The styled component will result in:

Prop Extension

Prismane allows developers to extend the prop types of its components, providing a flexible and customizable way to enhance component behavior. This is particularly useful when creating custom variations of components, such as a modified Button with additional styling options.

1. Understanding Prop Extension:

Prop extension allows developers to add custom props to existing prop types, providing a seamless way to introduce new features or styling options to a component.

2. Example: Extending `ButtonProps`:

Let's illustrate this concept with the Button component. Assume we want to introduce a custom prop called heavy, which, when set to true, makes the button's text appear in bold. Here's how you can achieve this:

// Importing ButtonProps from Prismane
import { ButtonProps } from '@prismane/core';

// Extending ButtonProps with a custom prop
interface StyledButtonProps extends ButtonProps {
  heavy?: boolean;
}

In this example, we create a new interface, StyledButtonProps, which extends the original ButtonProps. We then add a custom boolean prop, heavy, to represent whether the text should be displayed in bold.

3. Usage in Custom Button Component:

Now, you can use this extended prop type when defining your custom Button component:

import { Button } from '@prismane/core';

interface StyledButtonProps extends ButtonProps {
  heavy?: boolean;
}

// Custom Button component with extended props
const CustomButton: React.FC<StyledButtonProps> = ({ children, heavy, ...props }) => {
  // Applying additional styling based on the 'heavy' prop
  const fontWeight = heavy ? 'bold' : 'normal';

  return (
    <Button fw={fontWeight} variant="secondary" color="teal" br="full" {...props}>
      {children}
    </Button>
  );
};

By leveraging prop extension, you've seamlessly integrated a new customization option (heavy) into your Button component. This demonstrates how Prismane's prop extension capabilities enhance the extensibility and versatility of its components.

And if we now set heavy to true in our App.tsx

import StyledButton from "./components/StyledButton";

function App() {
  return (
    <StyledButton heavy>Custom Button</StyledButton>
  );
}

export default App;

Will change the look of our button to:

Amazing! You are now able to leverage Prismane’s components and create amazing looking UI’s!

Thank you for reading!

Feel free to connect with us on Twitter, GitHub, Reddit

You can support us through Contributing and OpenCollective.

Check out our website for more in detail information.

Form Validation with Zod and Prismane

Prismane — Wed, 13 Dec 2023 23:18:40 +0000

05 - Form Validation with Zod

Introduction

Greetings, everyone! Welcome to our tutorial on form validation in Prismane using the Zod library.

Zod is a TypeScript-first schema declaration and validation library. It allows developers to define data structures (schemas) in a type-safe manner and provides validation functions to ensure that data adheres to the specified structure.

By using Zod in Prismane, developers can leverage their form validation even more by easily creating more complex validators.

All of the code in the example below can be directly accessed through the GitHub Repository.

Before continuing, you should get familiar with the Zod library, if you are not.

Initial Setup

From this point on, we will accept that you understand how Prismane’s useForm hooks works and you know how to build forms using Prismane. If not, please refer to this tutorial.

Install Zod

Firstly, we need to install the zod package from the npm registry. We can do this by running this command:

npm install zod

Initial App

Now, we are going to use this initial app built only with Prismane:

import {
  Center,
  Card,
  Form,
  Button,
  TextField,
  PasswordField,
} from "@prismane/core";
import { useForm } from "@prismane/core/hooks";
import { z } from "zod";

function App() {
  const { handleSubmit, handleReset, register } = useForm({
    fields: {
      username: {
        value: "",
        validators: {
          required: (v) => p(v, z.string()),
          min: (v) => p(v, z.string().min(5)),
        },
      },
      password: {
        value: "",
        validators: {
          required: (v) => p(v, z.string()),
          min: (v) => p(v, z.string().min(5)),
        },
      },
    },
  });

  return (
    <Center w="100vw" h="100vh">
      <Card w={300} h={400}>
        <Form
          onSubmit={(e: any) => {
            handleSubmit(e, (v: any) => console.log(v));
          }}
          onReset={() => handleReset()}
        >
          <TextField
            placeholder="Enter username: "
            label="Username:"
            {...register("username")}
          />
          <PasswordField
            placeholder="Enter password: "
            label="Password:"
            {...register("password")}
          />
          <Button variant="primary" type="submit">
            Submit
          </Button>
        </Form>
      </Card>
    </Center>
  );
}

export default App;

💡 This application creates a form using the useForm hook, creates a form and registers two fields - username and password.

Adapt Zod to Prismane Validators

Great! Now, let's solve a key problem. Zod's validators don't work seamlessly with Prismane by default. To fix this, we'll create a function that adapts Zod validators to fit Prismane's form validation style. This way, you can smoothly use Zod with Prismane for your forms.

Firstly, let’s create the zodToPrismane file, where we will create our transform function.

touch zodToPrismane.ts

Then, inside the zodToPrismane.ts file, we are going to add the following function:

const p = (value: any, validator: any) => {
  const result = validator.safeParse(value);

  if (!result.success) {
    return result.error.errors[0].message;
  }

  return null;
};

export default p;

We are going to name it p so it can be shorter and not visually blocking when we use it.

The p function executes Zod's validator and provides the error message if there's one, or null if there are no errors. This way we can adapt the Zod validator to the structure of a Prismane validator.

Add Validators

Now, after having the p function, we can easily add Zod validators to Prismane’s useForm hook:

...
import p from "./zodToPrismane";
...

...
const { handleSubmit, handleReset, register } = useForm({
  fields: {
    username: {
      value: "",
      validators: {
        required: (v) => p(v, z.string().min(1)),
        min: (v) => p(v, z.string().min(5)),
      },
    },
    password: {
      value: "",
      validators: {
        required: (v) => p(v, z.string().min(1)),
        min: (v) => p(v, z.string().min(5)),
      },
    },
  },
});
...

💡 We are adding two validators to each of our fields - required and min.

The required validator isn’t directly supported by Zod, so we will have to check if the length of the value is at least 1 using the .min() property of the z.string() validator.

The min validator can be created by using the .min() property of the z.string() validator.

Let’s see the current result:

Customizing the Error Messages

With Zod, we can modify the default error messages to create more personalized errors for our fields.

For the required validator we can pass an object to the z.string().min() and give a value to the message property.

username: {
 ...
  validators: {
    required: (v) => p(v, z.string.min(1, {
      message: "The username field is required!",
    })),
        ...
  },
},
password: {
  ...
  validators: {
    required: (v) => p(v, z.string.min(1, {
      message: "The password field is required!",
    })),
    ...
  },
},

For the min validator we can pass an object as a second parameter to the .min() and give a value to the message property.

username: {
  ...
  validators: {
    ...
    min: (v) =>
      p(
        v,
        z.string().min(5, {
          message: "Username must be longer than 5 characters!",
        })
      ),
  },
},
password: {
  ...
  validators: {
    ...
    min: (v) =>
      p(
        v,
        z.string().min(5, {
          message: "The password must be longer than 5 characters!",
        })
      ),
  },
},

Great! Now all of the error messages are changed and personalized for the fields that we have and use.

Now, let’s see the final result:

Great, now you can build even form validators with ease using Prismane and Zod!

Feel free to connect with us on Twitter, GitHub, Reddit

You can support us through Contributing and OpenCollective.

Check out our website for more in detail information.

Form Building with Prismane

Prismane — Thu, 07 Dec 2023 16:58:27 +0000

Introduction

Greetings, everyone! Welcome to our tutorial on form building with Prismane. Throughout this guide, we'll explore the process of constructing forms using Prismane and dive into the utilization of our built-in validators. Let's embark on this journey together!

All of the code in the example below can be directly accessed through the GitHub Repository.

useForm hook

Prismane makes form building straightforward. By leveraging the useForm hook, you gain a seamless approach to constructing, validating, and handling forms. The upcoming section provides step-by-step guidance on creating a basic login form.

Import hook

We can import the useForm hook from the @prismane/core/hooks entry.

import { useForm } from "@prismane/core/hooks"

Initialize the hook

Now, we can initialize the hook and get the handleReset , handleSubmit and the register functions.

The handleReset function manages form resets by clearing the hook's state upon reset.

The handleSubmit function handles the form submit, and provides the state values of the form and the state of the form. The handleSubmit accepts up to three parameters. The first one is the event object, the second one is the onSubmit callback function and the last one is the onError callback function that is called, when the form fails to validate.

The register function simplifies field registration, ensuring proper and necessary props are assigned.

const { handleReset, handleSubmit, register } = useForm({})

Add fields to the hook

Great! Now, we have to tell our hook what fields we are going to have. Simply provide a fields property within the configuration object passed to the useForm hook.

Within the fields object, include properties with names corresponding to the intended field names.

For each field, set a value property indicating the initial value of the field.

In our case we are going to have a username and a password fields.

const { handleReset, handleSubmit, register } = useForm({
    fields: {
        username: {
            value: ""   
        },
        password: {
            value: ""
        }   
    }
})

Add Form

Now, we need to add our Form and pass the onSubmit and onReset props.

import { Center, Card, Form } from "@prismane/core";
import { useForm } from "@prismane/core/hooks";

function App() {
  const { handleReset, handleSubmit, register } = useForm({
    fields: {
      username: {
        value: "",
      },
      password: {
        value: "",
      },
    },
  });

  return (
    <Center w="100vw" h="100vh">
      <Card>
        <Form
          onSubmit={(e: SubmitEvent) => handleSubmit(e, (v) => console.log(v))}
                    onReset={handleReset}
        ></Form>
      </Card>
    </Center>
  );
}

export default App;

As you can see, we've linked the handleSubmit function to the onSubmit event. We've supplied just two parameters to handleSubmit - the event object and the onSubmit callback function, responsible for logging values to the console upon successful submission.

Additionally, we assigned the handleReset function to the onReset prop, ensuring a reset of our components' values and form state.

Add fields

Now, let’s add our fields and a submit button. We are going to use the TextField for our username and the PasswordField for our password.

import { ..., TextField, PasswordField, Button } from "@prismane/core";
...

...
<Form
  onSubmit={(e: SubmitEvent) => handleSubmit(e, (v) => console.log(v))}
    onReset={handleReset}
>
  <TextField />
  <PasswordField />
    <Button type="submit">Submit Form</Button>
</Form>
...

Register fields

Great! Now, lets register our fields. To do that, we are going to use the register function that we got from the useForm hook.

We need to pass a single parameter to the register function, which is the name of the field undergoing registration.

💡Make sure to provide the same name to the register function, as the one that you provided in the fields object, otherwise the field will not register correctly!

The register function returns an object that contains essential field properties. Because of that, we must spread this function across the component. The register function returns properties such as onChange, onBlur, onFocus, value, name, and id.


...
  <TextField {...register("username")} placeholder="Enter username" label="Username:" />
  <PasswordField {...register("password")} placeholder="Enter password" label="Password:" />
...

Great! Now, let’s try out our form and see what is logged to the console!

Prismane’s Validators

Every field within the useForm hook has a validators property. Within this property's object, we list the validators assigned to the field.

The validators must be added in following order, because the hook validates them one by one. If one returns an error, the hook stops validating and handles the error.

Each validator is represented by a function that takes the field's value as the parameter v, passes this value to the validator function, and then invokes the validator function.

Prismane's validator functions return null when there is no error. In case of an error, they provide an error message as a string.

Adding Validators

In our example, we are going to add the required and username validators to our username field and we are going to add the required and the min validator to the password field.

The required validator ensures that the given value is defined and not empty, confirming it has a valid and meaningful content. It can handle both numbers, strings and booleans.

The username validators checks if the provided value is a valid username or not. It’s regex can be overwritten, if you provide a regex as the second parameter.

The min validator checks if the provided value’s length is more than a given number. The error message can be personalized to the field, by providing a third parameter, which is the field’s name.

Import validators

Firstly, we have to import our validators from the @prismane/core/validators entry.

import { required, username, min } from "@prismane/core/validators";

Add validators to fields in useForm hook

Next, we are going to add the validators to the validators property of each of our fields.

...
username: {
  value: "",
  validators: {
    required: (v) => required(v),
    username: (v) => username(v),
  },
},
password: {
  value: "",
  validators: {
    required: (v) => required(v),
    min: (v) => min(v, 4),
  },
},
...

Great! Now, let’s see the final result

💡 As you can see, form submission is unavailable until all of the fields are error-free.

Fantastic job! You now can successfully create forms and handle them using Prismane!

Thank you for reading!

Feel free to connect with us on Twitter, GitHub, Reddit
You can support us through Contributing and OpenCollective.
Check out our website for more in detail information.

Advanced Styling with Prismane

Prismane — Sat, 02 Dec 2023 17:17:28 +0000

Introduction

Hello, everyone! Welcome to this advanced tutorial on Styling with Prismane. In this tutorial, you will understand how powerful and versatile Prismane’s styling system really is.

Empower your React development with Prismane's comprehensive arsenal of tools: 26+ hooks, 111+ components, and 28+ form validators. Craft seamless forms with Prismane's intuitive form builder. Experience unparalleled performance, as every component is meticulously optimized for speed and efficiency.

All of the code in the example below can be directly accessed through the GitHub Repository.

Styling Components with Prismane

In this section, we will demonstrate how to style components using Prismane. We will cover various styling options, CSS variables, and component-based theming.

Shorthand Props

Prismane's shorthand props make it easy to quickly style components without writing lengthy CSS rules. This can save you time and effort, and make your code more readable and maintainable. Additionally, Prismane's shorthand props have support for pseudo-classes, at rules and much more.

Instead of lengthy CSS rules, use the shorthand props to effortlessly customize components like the Box without the need for additional CSS.

.PrismaneBox-root {
  padding: 16px !important;
  background: red;
  color: white;
}

We can write the following code, which will produce the same output:

<Box p={16} bg="red" cl="white" />

The p prop sets the padding of the button to 16px

The bg prop sets the background of the button to red

The cl prop sets the color property of the button to white

💡 All of Prismane’s components support these shorthand props. To learn more about the full list of shorthand props, you can check out this documentation.

Customizing A Button Component

Using the shorthand props that Prismane exposes, you can craft a new component, tailor the Button component to your preferences, and reuse it by following these steps:

import { Button, ButtonProps } from "@prismane/core";

const NewButton = ({ children, ...props }: ButtonProps) => {
  return (
    <Button px={18} py={12} br={0} {...props}>
      {children}
    </Button>
  );
};

export default NewButton;

The px prop sets the horizontal padding of the button to 18px

The py prop sets the vertical padding of the button to 12px

The br prop sets the border-radius property of the button to 0

💡 We are using the ButtonProps type from Prismane’s Button component. This way we are ensuring that the new component still has TypeScript support.

Following these steps, you have created a fully customized NewButton component that still has all of the functionality of the Button component.

Let’s see the result

Pseudo Classes

All of Prismane’s shorthand props have support for pseudo-classes. To fully understand all of Prismane’s shorthand props’ features, check out this tutorial.

To add a pseudo-class value, we need to pass an array to the shorthand prop. The first value of the array is the normal value, the second value of the array is an object whose keys are the names of the pseudo-classes, and it’s values are the respected values when the pseudo-class is active.

To easily understand how they work, let’s change the background of our button and change it once again on hover. This can be done as follows:

import { Button, ButtonProps } from "@prismane/core";

const NewButton = ({ children, ...props }: ButtonProps) => {
  return (
    <Button
      px={18}
      py={12}
      br={0}
      bg={["#40e495", { hover: "#2bb673" }]}
      {...props}
    >
      {children}
    </Button>
  );
};

export default NewButton;

This results in:

CSS Global Style Customization

All of Prismane's components have CSS classes for each of their layers, classes that are toggled by props, and classes that represent given prop values. This makes it easy to integrate Prismane components with your existing CSS styles.

Let’s use this App.tsx starter code and work our way through customizing our buttons globally.

import { Center, Button } from "@prismane/core";

function App() {
  return (
    <Center w="100vw" h="100vh" direction="column" gap={8}>
      <Button>Primary Button</Button>
      <Button variant="secondary" color="base">Secondary Button</Button>
    </Center>
  );
}

export default App;

This will render the following:

Now, we are going to use the Button component’s prebuilt classes to style our two buttons. You can find the full list of CSS classes that the Button component has in the Button API page.

💡 You can find the full list of CSS classes of any component by choosing the component from the Overview page.

Let’s make our buttons round by default. To do that, we can use the .PrismaneButton-root class that every Button component has. This class targets the root element of our Button which is the button element.

.PrismaneButton-root {
  border-radius: 9999px !important;
}

Let’s see the result

Great! Now, let’s add a linear-gradient to our primary button only. To do that, we can use the .PrismaneButton-{variant} class that Prismane exposes. Since we want to target only the buttons that have the primary variant, we are going to use this class - .PrismaneButton-primary

.PrismaneButton-primary {
  background: linear-gradient(to right, #11998e, #38ef7d) !important;
}

Let’s see the changes:

CSS Theme Variables

Prismane converts the Theme Object to CSS variables, which enables you to integrate them into your CSS Stylesheet.

CSS Theme Variables:

Primary Colors:

—prismane-colors-primary-50,

—prismane-colors-primary-100,

—prismane-colors-primary-200,

—prismane-colors-primary-300,

—prismane-colors-primary-400,

—prismane-colors-primary-500,

—prismane-colors-primary-600,

—prismane-colors-primary-700,

—prismane-colors-primary-800,

—prismane-colors-primary-900,

Base Colors:

—prismane-colors-base-50,

—prismane-colors-base-100,

—prismane-colors-base-200,

—prismane-colors-base-300,

—prismane-colors-base-400,

—prismane-colors-base-500,

—prismane-colors-base-600,

—prismane-colors-base-700,

—prismane-colors-base-800,

—prismane-colors-base-900,

Border Radius:

—prismane-border-radius-xs,

—prismane-border-radius-sm,

—prismane-border-radius-base,

—prismane-border-radius-md,

—prismane-border-radius-lg,

—prismane-border-radius-xl,

—prismane-border-radius-2xl,

Spacing:

—prismane-spacing,

Now, let’s customize our primary button gradient to use the primary theme colors:

.PrismaneButton-primary {
  background: linear-gradient(
    to right,
    rgb(var(--prismane-colors-primary-700)),
    rgb(var(--prismane-colors-primary-400))
  ) !important;
}

Let’s see the final result:

That is awesome! You are now a pro Prismane developer!

Thank you for reading!

Feel free to connect with us on Twitter, GitHub, Reddit

You can support us through Contributing and OpenCollective.

Check out our website for more in detail information.

Advanced Theming with Prismane

Prismane — Wed, 29 Nov 2023 22:12:19 +0000

Introduction

Hello, everyone! Welcome to this tutorial on Theming and Styling Prismane. In this tutorial, you will discover the power of Prismane and witness its full potential.

Prismane offers an extensive array of tools for you to utilize: over 26 hooks, more than 111 components, and an impressive collection of 28 form validators. With Prismane, you can enjoy a smooth and efficient form-building experience. What truly distinguishes Prismane is our unwavering commitment to performance. We meticulously craft each component and feature with the utmost focus on speed and efficiency.

All of the code in the example below can be directly accessed through the GitHub Repository.

Theming Techniques

In this section, we will learn how to change the theme of Prismane. You will discover that it is as easy as pie. We will explore how to customize colors, spacing, and more. We will also discuss best practices and tips for efficient theming.

From this point on, we will accept that you have installed Prismane in your React application. If that is not the case, please refer to this tutorial.

Example App

Let’s use this example application that contains two Button components, which we will style throughout our tutorial.

...
import { PrismaneProvider } from "@prismane/core";
import "@fontsource/poppins/100.css";
import "@fontsource/poppins/200.css";
import "@fontsource/poppins/300.css";
import "@fontsource/poppins/400.css";
import "@fontsource/poppins/500.css";
import "@fontsource/poppins/600.css";
import "@fontsource/poppins/700.css";
import "@fontsource/poppins/800.css";
import "@fontsource/poppins/900.css";
...

...
root.render(
  <React.StrictMode>
    <PrismaneProvider>
      <App />
    </PrismaneProvider>
  </React.StrictMode>
);
...

We are going to add two Button components stacked underneath each other. These buttons will be used as examples of how the theme changes affect the components throughout this tutorial. The first button will use the primary variant and the second one will use the secondary variant of the Button component.

import { Stack, Button } from "@prismane/core";

function App() {
  return (
    <Stack w="100vw" h="100vh" align="center" justify="center">
      <Button>Primary Button</Button>
      <Button variant="secondary">Secondary Button</Button>
    </Stack>
  );
}

export default App;

Great. Now we see the two buttons using the default theme that comes with Prismane.

Theming with Prismane

As we saw in the previous screenshot, Prismane uses a default theme object, which can be modified. The modification of the theme of Prismane is done by providing a new theme object to the PrismaneProvider component that wraps your application. This way, you can ensure that the new theme is applied to all of your components.

The new theme object can have only the properties of the PrismaneTheme type, which you want to change (overwrite). The ones that are missing, will be taken from the default theme.

The theme object defines various aspects of the theme, such as the mode (light or dark), colors, border radius, and spacing.

The mode prop determines the overall appearance of the theme, either light or dark. This setting affects various aspects of the UI, such as text and background colors, contrasts, and shadows.

The colors prop defines the palette of colors used throughout the theme. It includes properties for primary and base colors. These colors are used for elements like buttons, links, headings, and borders.

The borderRadius prop controls the roundedness of corners in various UI components. It can be specified as an object with specific values for different breakpoints.

The spacing prop defines the default spacing between UI elements. These values ensure consistent and visually appealing scaling throughout components.

Theme Object Type

export interface PrismaneTheme {
  // The theme mode "dark" or "light"
  mode: "light" | "dark";

  // The theme colors
  colors: {
    primary: {
      50: string;
      100: string;
      200: string;
      300: string;
      400: string;
      500: string;
      600: string;
      700: string;
      800: string;
      900: string;
    };
    base: {
      50: string;
      100: string;
      200: string;
      300: string;
      400: string;
      500: string;
      600: string;
      700: string;
      800: string;
      900: string;
    };
  };

    // The borderRadius that the components use
    borderRadius: {
      xs: string;
      sm: string;
      base: string;
      md: string;
      lg: string;
      xl: string;
      "2xl": string;
  };


  // The theme spacing, changing it will scale up or down the size of your components
  spacing: string;
}

Base Theme

Here you can see the properties of the default theme object that Prismane comes with.

const base: PrismaneTheme = {
  mode: "light",
  colors: {
    primary: {
      // Prismane's diamond colors
      50: "#f0f9ff",
      100: "#e0f2fe",
      200: "#bae6fd",
      300: "#7dd3fc",
      400: "#38bdf8",
      500: "#0ea5e9",
      600: "#0284c7",
      700: "#0369a1",
      800: "#075985",
      900: "#0c4a6e",
    },
    base: {
      // Prismane's gray colors
      50: "#f9fafb",
      100: "#f3f4f6",
      200: "#e5e7eb",
      300: "#d1d5db",
      400: "#9ca3af",
      500: "#6b7280",
      600: "#4b5563",
      700: "#374151",
      800: "#1f2937",
      900: "#111827",
    },
  },
  spacing: "4px",
    borderRadius: {
    xs: fr(0.75), // 3px, when spacing is 4px
    sm: fr(1), // 4px, when spacing is 4px
    base: fr(1.5), // 6px, when spacing is 4px
    md: fr(2), // 8px, when spacing is 4px
    lg: fr(2.5), // 10px, when spacing is 4px
    xl: fr(3), // 12px, when spacing is 4px
    "2xl": fr(3.5), // 14px, when spacing is 4px
  },
};

export default base;

Theme Colors Configuration

To customize the theme colors, as mentioned earlier, we need to provide values for the “colors” property of the a new theme object.

💡 The colors property of both primary and base must be objects. The keys of these objects should correspond to the desired shades (100 - 900). If a specific shade is not provided, the corresponding shade from the theme will be used as the default.

Prismane comes with a prebuilt color palette that users can choose from, but it is not necessary. Users can provide their own color values if they prefer.

For the purpose of this tutorial, we are going to use the the Ruby and the Coal colors from our Color Palette.

To get access to these colors, we have to import the PRISMANE_COLORS global from the root entry of our package. The PRISMANE_COLORS global gives us access to Prismane’s predefined color palette.

import { PRISMANE_COLORS } from "@prismane/core";

After that, we can set the “primary” and “base” properties of the “colors” key of our new theme theme object.

const theme = {
  colors: {
    primary: PRISMANE_COLORS.ruby,
    base: PRISMANE_COLORS.coal,
  },
};

The last step is to pass the new theme object to the PrismaneProvider component using the “theme” prop.

<PrismaneProvider theme={theme}>
  <App />
</PrismaneProvider>

Let’s see the result

Great! Now you have successfully changed the theme colors of your application!

Theme Spacing Configuration

Prismane comes with scaling being core part of the theming ability. The scaling is controlled by the “spacing” property of the theme object and using it we can scale our components globally.

By default, the spacing property has a value of 4px .

The font-size of the document is calculated using this formula and is automatically applied when Prismane is installed.

html {
  font-size: calc(4 * var(--prismane-spacing));
}

All of Prismane’s components have sizes in rem thanks to the fr function, which means that by changing the font-size of the document, we will scale our components.

So, in short terms, to scale our components, we just need to pass a value to the spacing prop of the theme object we created.

const theme = {
  ...
  spacing: "6px",
};

Let’s see the result

Theme Border Radius Configuration

We can change the predefined fixed border-radius sizes, by changing the value of the borderRadius property of the theme object.

💡 The borderRadius property is related to the spacing property of the theme, because it uses the fr function to set it’s predefined sizes, by default. This way, when the components are scaled, so does the border radius. We recommend to use the fr function when overwriting the borderRadius to keep this functionality.

If you are not familiar with the fr function, please refer to the documentation.

Let’s import the fr function from the root entry of our package.

import { ..., fr } from "@prismane/core";

Let’s make our buttons a little duller by passing specific values for each size.

const theme = {
  ...
  borderRadius: {
    xs: fr(0.25), // 1px, when spacing is 4px
    sm: fr(0.5), // 2px, when spacing is 4px
    base: fr(0.75), // 3px, when spacing is 4px
    md: fr(1.25), // 5px, when spacing is 4px
    lg: fr(1.75), // 7px, when spacing is 4px
    xl: fr(2.25), // 9px, when spacing is 4px
    "2xl": fr(2.75), // 11px, when spacing is 4px
  },
};

Let’s see the changes

Great! Now you are fully capable of customizing your Prismane theme with ease and developing it with ease!

Thank you for reading!

Feel free to connect with us on Twitter and GitHub.

Check out our website for more detailed information

DEV Community: Prismane

Custom Components with Prismane

Prerequisites

Initial Component

Prop Types in Prismane

Prop Types Naming Convention

Accessing Prop Types

Custom Button Component

Understanding the Prismane Button Component

Integrating the Button Component from Prismane

Using the StyledButton Component

Styling the new StyledButton Component

Prop Extension

1. Understanding Prop Extension:

2. Example: Extending ButtonProps:

3. Usage in Custom Button Component:

Thank you for reading!

Form Validation with Zod and Prismane

05 - Form Validation with Zod

Introduction

Initial Setup

Install Zod

Initial App

Adapt Zod to Prismane Validators

Add Validators

Add Validators

Customizing the Error Messages

Form Building with Prismane

Introduction

useForm hook

Import hook

Initialize the hook

Add fields to the hook

Add Form

Add fields

Register fields

Prismane’s Validators

Adding Validators

Import validators

Add validators to fields in useForm hook

Thank you for reading!

Advanced Styling with Prismane

Introduction

Styling Components with Prismane

Shorthand Props

Customizing A Button Component

Pseudo Classes

CSS Global Style Customization

CSS Theme Variables

Thank you for reading!

Advanced Theming with Prismane

Introduction

Theming Techniques

Example App

Theming with Prismane

Theme Object Type

Base Theme

Theme Colors Configuration

Theme Spacing Configuration

Theme Border Radius Configuration

Thank you for reading!

2. Example: Extending `ButtonProps`: