@nottimtam/proton.js v1.0.8

proton.js

A small, easy-to-learn UI library for Next.js/React.js

Proton is not a full UI library, instead it is a collection of highly modifiable components for you to drop into existing projects.

All icons used in this library are from bootstrap-icons, but it is not required as a dependency.

Proton works well with these libraries:

• bootstrap-icons npm i bootstrap-icons
• react-icons npm i react-icons

Documentation

Importing

All components can be imported with:

import { ComponentName } from "proton.js";

Applying Modifications

You can apply style/state changes to each component either through attributes. Example:

return <Component icon emphasis="primary" />;

Some component states require certain types of values, but the majority are just booleans. Both of the below examples produce the same effect:

return <>
	<! -- Effectively the same. -- >
	<Component icon />
	<Component icon={true}>
</>;

Any other attributes added to the component will be accepted like normal by React.js/Next.js. (i.e. className, style, key)

Colors

You can apply colors to most of the components with a color attribute.

return <Component color="red" />;

Here is a list of the available colors. You can always modify the colors in the styles folder to suite your needs.

Certain components can have emphasis applied to them. This can be:

• primary (purple),
• secondary (grey),
• or, none (default)

Components

Button

The button component has a variety of animations and styles for you to pick from.

import { Button } from "proton.js";

return <Button>Text/Children Here</Button>;

States

Style Modifications

Button Group

The button group holds an unlimited number of <Button/>s in a stylish and compact way.

import { Button } from "proton.js";

return (
	<Button.Group>
		...<Button></Button>
	</Button.Group>
);

Style Modifications

Button Label

A button label goes inside of a button and can be used for icons, to indicate data, or whatever else you what emphasis applied to.

import { Button } from "proton.js";

return (
	<Button>
		Cart
		<Button.Label>{cart.length}</Button.Label>
	</Button>
);

Style Modifications

Progress Bar

The progress bar allows you to display a percentage value with any text over it.

import { ProgressBar } from "proton.js";

return (
	<ProgressBar value={50} min={0} max={100}>
		<ProgressBar.Label>Hello</ProgressBar.Label>
		<ProgressBar.Label>World</ProgressBar.Label>
	</ProgressBar>
);

States

Style Modifications

Progress Bar Spacer

The spacer goes inside of a progress bar and takes up as much space as it can.

import { ProgressBar } from "proton.js";

return (
	<ProgressBar value={50} min={0} max={100}>
		<ProgressBar.Label>Hello</ProgressBar.Label>
		<ProgressBar.Spacer />
		<ProgressBar.Label>World</ProgressBar.Label>
	</ProgressBar>
);

States

Progress Bar Label

The label is a box that should contain any inner content for the bar, excluding spacers. You can have multiple spacers and they will stay in the bar properly spaced. Please keep in mind that the progress bar should maintain a horizontal line and won't wrap properly.

import { ProgressBar } from "proton.js";

return (
	<ProgressBar value={50} min={0} max={100}>
		<ProgressBar.Label>Hello</ProgressBar.Label>
		<ProgressBar.Label>World</ProgressBar.Label>
	</ProgressBar>
);

Consistency is key to making the progress bar flow properly. I.e.:

• If one label contains a dot component, all of them should.

import { ProgressBar } from "proton.js";

return (
	<ProgressBar value={50} min={0} max={100}>
		<ProgressBar.Label>
			<ProgressBar.Dot /> <!-- Good -->
		</ProgressBar.Label>
		<ProgressBar.Label>
			<ProgressBar.Dot /> <!-- Good -->
		</ProgressBar.Label>
		<ProgressBar.Label>
			<!-- Should have a dot -->
		</ProgressBar.Label>
	</ProgressBar>
);

• All dots should be the first element in the label.

import { ProgressBar } from "proton.js";

return (
	<ProgressBar value={50} min={0} max={100}>
		<ProgressBar.Label>
			<ProgressBar.Dot /> <!-- Good -->
			Text
		</ProgressBar.Label>
		<ProgressBar.Label>
			<ProgressBar.Dot /> <!-- Good -->
			Text
		</ProgressBar.Label>
		<ProgressBar.Label>
			Text
			<ProgressBar.Dot /> <!-- Bad, dots always go first. -->
		</ProgressBar.Label>
	</ProgressBar>
);

• If a label contains text and dot components, and the progress bar has a backline property, then all of the labels in the bar should contain text to have the dots line up properly.

import { ProgressBar } from "proton.js";

return (
	<ProgressBar value={50} min={0} max={100}>
		<ProgressBar.Label>
			<ProgressBar.Dot /> <!-- Good -->
			Text
		</ProgressBar.Label>
		<ProgressBar.Label>
			<ProgressBar.Dot /> <!-- Good -->
			Text
		</ProgressBar.Label>
		<ProgressBar.Label>
			<ProgressBar.Dot />
			<!-- No text means this dot will be unaligned. -->
		</ProgressBar.Label>
	</ProgressBar>
);

Progress Bar Dot

Dots are nice indicators of "steps" inside of a progress bar. They should be contained within labels. They can also be displayed alongside text, but the styling rules described in the label rules must be followed.

import { ProgressBar } from "proton.js";

return (
	<ProgressBar value={50} min={0} max={100} backline>
		<ProgressBar.Label>
			<ProgressBar.Dot />
		</ProgressBar.Label>

		<ProgressBar.Label>
			<ProgressBar.Dot />
		</ProgressBar.Label>
	</ProgressBar>
);

Style Modifications

Pagination

The pagination component is a simple yet effective button group for pagination.

The paginator does not store page data or load it, it simply allows users to change their page number in an intuitive way, that the developer can use to modify the content of their pages.

import { Pagination } from "proton.js";
import { useState } from "react";

// An example of a fully functional paginator.
const myPage = () => {
	const [page, setPage] = useState(1);

	return (
		<Pagination
			activePage={page}
			totalPages={5}
			onPageChange={(page) => setPage(page)}
		/>
	);
};

States

The minimum outside code to get this to work is a single useState that stores the current page. (or equivalent)

onPageChange

The onPageChange function is what makes the paginator work.

Example: onPageChange={(page) => setPage(page)}

This attribute passes a function through to the paginator, telling it what to do when it changes a page.

For instance, in the above example, the paginator will hand its new page number to the function, which is then used to overwrite a state.

Other functions can be used, so long as the activePage property is kept consistent with the new page number.

overrideButtonContent

The overrideButtonContent function is for more advanced developers who want to change the content of the page number buttons.

It takes in one parameter, the page number, and returns whatever content the developer would like. This can be HTML content, plaintext, and more.

Example: overrideButtonContent={(pageNumber) => `${pageNumber}/${maxPages}`}

Instead of the default, the above example will make each page number button display a fraction. I.e.: "4/50".

Style Modifications

Input