Admin Bar Component is a web component that is built with Lit. It can be added to projects that can load web components (vanilla JavaScript and most modern frameworks) and it is customizable so you can choose what buttons are displayed, and you can style it to match your brand or website’s look and feel.
- 👋 Show an avatar and a greeting to confirm the currently logged-in user.
- 🚧 A customizable environment warning can be shown to let users know they are not on production.
- 🎛️ Buttons are customizable and can link to a URL or trigger JavaScript events.
- 2️⃣ Text elements can be added to provide stats and small notes to authors.
- 🚪 A dedicated logout button gives users a way to sign out of your app.
To install Admin Bar Component, use NPM or a compatible package manager.
npm install admin-bar-component --save-dev
This package includes a JavaScript file that registers web components when you import it into a file or load it with a <script type="module">
tag.
It also includes a CSS file that can be imported into your project’s CSS or loaded onto the page in a <link>
tag.
- CodePen – Basic Usage
- CodePen – Kitchen Sink
- Stackblitz – Theme Examples
- Stackblitz – Vite + Vanilla JS
- Stackblitz – Vite + Vue.js 3
- Add the stylesheet in your
<head>
tag:<link rel="stylesheet" href="path-to-your-assets/admin-bar.css" />
- Add the JavaScript file wherever you load your scripts:
<script type="module" src="path-to-your-assets/admin-bar.js"></script>
- Add and configure an
<admin-bar>
element:<admin-bar></admin-bar>
- Add buttons into your
<admin-bar>
element:<admin-bar> <admin-bar-button></admin-bar-button> </admin-bar>
- In a global JavaScript file or in a specific layout or component file, you can import the JavaScript file like this:
import 'admin-bar-component'
- You can load the CSS in your component file, as well, by importing the file directly:
import 'admin-bar-component' import 'admin-bar-component/dist/admin-bar.css'
- Or, if you are using something like PostCSS, you can import the CSS file into your CSS file, like this:
@import url(admin-bar-component/dist/admin-bar.css);
Depending on what bundler or framework you are using, you may need to add loaders or register the web component as a custom element (telling the framework not to try to render it).
All of the features on the <admin-bar>
element are opt-in by using attributes and slots.
For example, you can add a greeting message by adding the show-greeting
attribute:
<admin-bar show-greeting></admin-bar>
By default, this will say "Hello", but you can change the message by adding your own text or element into the greeting
slot:
<admin-bar show-greeting>
<div slot="greeting">Hello, Sam</div>
</admin-bar>
Now your custom text will appear. If you would also like to add an avatar next to your message you can use the avatar-src
and avatar-alt
attributes:
<admin-bar show-greeting avatar-src="path-to-your-assets/user-photo.jpg" avatar-atr="Sam’s avatar">
<div slot="greeting">Hello, Sam</div>
</admin-bar>
Note
If show-greeting
is removed, the avatar image and the content in the greeting
slot will no longer be rendered.
Attribute Name | Type | Default | Description |
---|---|---|---|
avatar-alt |
string | 'Avatar of logged in user.' |
Sets the alt text on an avatar image. |
avatar-src |
string | undefined |
Sets the src on an avatar image and enables the avatar image to be displayed. |
greeting-text |
string | 'Hello' |
Sets the greeting text content. |
logout-href |
string | '#' |
A URL added to the default logout button, when show-logout is added to an <admin-bar> . |
logout-label |
string | 'Sign out' |
The label of the default logout button. |
show-environment |
boolean | false |
Displays the environment warning, letting users know what environment they are currently logged into. |
show-greeting |
boolean | false |
Displays the avatar and greeting message. |
show-logout |
boolean | false |
Displays the default logout button or content added to the logout slot. |
Slot Name | Description |
---|---|
default |
The default slot is where you would place <admin-bar-button> elements, but it can also be used for other elements. All children in the default slot will be laid out by CSS Flexbox and the contents will horizontally scroll when it gets too wide. |
greeting |
This slot is meant to let the logged-in user verify they are logged in, but any HTML or text can appear in the greeting slot. |
logout |
When show-logout is set, a default logout button will be rendered, using the logout-href and logout-label attributes. Adding elements into the logout slot will repace the default logout button, allowing you to use your own <admin-bar-button> in its place. |
Admin Bar Buttons are child web components that render either an <a>
element or a <button>
element—depending on the options you pass through.
To create an <a>
element that links to a URL, you can add a label and a button-href
attribute that includes your URL:
<admin-bar-button button-href="https://myexample.com" label-text="My Link Label"></admin-bar-button>
To create a <button>
element with JavaScript click event, you can leave off the button-href
and the component will switch over to a button element:
<admin-bar-button onclick="myEventHandlerMethod" label-text="My Button Label"></admin-bar-button>
To differentiate your buttons, <svg>
or <img>
icons can be added to either the label-before
or label-after
slots:
<admin-bar-button onclick="myEventHandlerMethod" label-text="My Button Label"><span slot="label-before"><svg <!-- SVG code --> ></svg></span></admin-bar-button>
Populating the popover
slot will render the popover
slot and add a matching popovertarget
attribute to the <admin-bar-button>
. Clicking on the <admin-bar-button>
will open the popover. Clicking or focusing anywhere away from the popover content will hide the popover content again.
Note
The popover
slot content appears below its <admin-bar-button>
on browsers that support CSS Anchor Positioning. Browsers that don’t support CSS Anchor Positioning yet will fall back to displaying the popover
slot in the center of the screen (which is the default for HTML popover).
Any HTML can be added to the popover
slot, but for consistency, you can use <admin-bar-text>
elements or <admin-bar-button>
elements. Here’s an example of what an <admin-bar-text>
popover could look like:
<admin-bar-button>Show Popover<span slot="popover"><admin-bar-text>Hi, this is popover content 🍾</admin-bar-text></span></admin-bar-button>
The "Show Popover" text will appear as the label on the button and "Hi, this is popover content 🍾" will appear in the popover when the button is clicked.
To create a secondary row of links, you can populate the popover
slot with <admin-bar-button>
elements:
<admin-bar-button>Popover Slot 2<nav slot="popover">
<admin-bar-button button-href="https://craftcms.com">Craft CMS</admin-bar-button>
<admin-bar-button button-href="https://laravel.com">Laravel</admin-bar-button>
</nav></admin-bar-button>
Note
To make the links appear in a row, you can use CSS to style the nav
element here to use display: flex;
.
Attribute Name | Type | Default | Description |
---|---|---|---|
button-href |
string | undefined |
Adding the button-href turns the <admin-bar-button> into an <a> elements and sets this string as its href attribute. |
label-text |
string | '' |
Sets the label for the <admin-bar-button> . |
logout-button |
boolean | false |
Styles the button like the default logout button. |
Slot Name | Description |
---|---|
after-label |
Adds content after the label. This can be used for icons or other indicators. |
before-label |
Adds content before the label. This can be used for icons or other indicators. |
default |
Adding text or elements into the default slot replaces the label-text . |
popover |
Turns the button into a trigger and displays slot content in a popover. |
You may have a situation where you need to replace the default logout button to—for example—a button that fires a JavaScript action. Starting with this code as an example, you can do the following:
<admin-bar show-logout logout-href="/logout" logout-label="Log off"></admin-bar>
- Add an
<admin-bar-button>
into thedefault
slot of your<admin-bar>
<admin-bar show-logout logout-href="/logout" logout-label="Log off"> <admin-bar-button></admin-bar-button> </admin-bar>
- Add
slot="logout"
to the<admin-bar-button>
. Add thelogout-button
attribute to style the button with the styles from the default logout button.<admin-bar show-logout logout-href="/logout" logout-label="Log off"> <admin-bar-button slot="logout" logout-button></admin-bar-button> </admin-bar>
- If you are using vanilla JavaScript you can use an
onclick
attribute to fire your logout script on click. If you are using a compatible framework, you can changeonclick
to the syntax used for click directives.<admin-bar show-logout logout-href="/logout" logout-label="Log off"> <admin-bar-button onclick="handleLogoutMethod" slot="logout" logout-button></admin-bar-button> </admin-bar>
- This replaces the original logout buttons, so you no longer need the
logout-href
andlogout-label
attributes. You still need theshow-logout
attribute to render the logout slot.<admin-bar show-logout> <admin-bar-button onclick="handleLogoutMethod" slot="logout" logout-button></admin-bar-button> </admin-bar>
The default slot of an <admin-bar>
element is an element with display: flex
on it. This means you can add <admin-bar-button>
elements alongside any other HTML element you would like display next to them. You can add a <div>
with text in it and use CSS to style it however you'd like, however, if you would simply like to display some text, you could use a <admin-bar-text>
element:
<admin-bar>
<admin-bar-text text-content="Hello, World!"></admin-bar-text>
</admin-bar>
Using the text-content
attribute will add plain text that is styled to look like the text in Admin Bar’s greeting. If you would like to style the text differently or if you would like to add your own HTML elements into the <admin-bar-text>
element, you can use the default slot to add elements:
<admin-bar>
<admin-bar-text>Hello, World!</admin-bar-text>
</admin-bar>
You can use <admin-bar-text>
elements for notes or for other useful information that is tied to the context of the current page you are on. Using the label-content
attribute on a <admin-bar-text>
element will let you call out stats and other information:
<admin-bar>
<admin-bar-text label-content="25" text-content="Enries in this Section"></admin-bar-text>
</admin-bar>
If you would like to create a text element that is made up of only a label, you can omit the default slot and the text-content
attribute:
<admin-bar show-environment>
<admin-bar-text label-content="STAGING"></admin-bar-text>
</admin-bar>
Tip
The color of labels can be styled using CSS Custom Properties. This can be helpful in alerting users of important information.
Text in <admin-bar-text>
elements are not allowed to wrap by default, but adding the multi-line
attribute unsets the CSS that keep its content on one line.
<admin-bar>
<admin-bar-text multi-line>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Accusamus beatae corporis dicta, eum illum numquam quos reiciendis sequi ut. Alias culpa eum itaque molestiae mollitia quas qui saepe veniam, voluptatum.</admin-bar-text>
</admin-bar>
Attribute Name | Type | Default | Description |
---|---|---|---|
label-content |
string | '' |
Sets the label for the <admin-bar-text> . |
label-position |
string | 'after' |
Sets the position for the label. Accepts: 'after' , 'before' |
multi-line |
boolean | false |
Allows the content to wrap to the next line. |
text-content |
string | '' |
Sets the text content for the <admin-bar-text> . This can be used instead of the default slot. |
Slot Name | Description |
---|---|
default |
Text or HTML elements rendered in the <admin-bar-text> element. |
Admin Bar Component is a web component that renders via the Shadow DOM. This means that Admin Bar Component won’t pick up the styles from your project’s stylesheets, but it also means that you cannot directly style children in the <admin-bar>
and <admin-bar-button>
components.
Note
Slot content is an exception. They will pick up some styles from the web component CSS, but you can also use CSS to style them in your stylesheet.
Classes, CSS Cascade Layers, CSS Custom Properties can be used to customize the look of your Admin Bar.
Classes can be added to <admin-bar>
elements to change the look and placement of the element on your page.
Class | Description |
---|---|
bottom |
Works along side the fixed or sticky class to move the <admin-bar> to the bottom of the page (sets the bottom CSS property to 0 and the top to auto ). |
fixed |
Makes the <admin-bar> fixed to the top of the page, using CSS position: fixed . When using fixed you can move <admin-bar> to the bottom of your <body> element. |
rtl |
Changes the reading direction from ltr to rtl in situations where you need to manually set it. Admin Bar Component will automatcally switch to RTL if your page is set to RTL or if you have the CSS set to direction: rtl . |
sticky |
Makes the <admin-bar> stick to the top of the page, using CSS position: sticky when the <admin-bar> is above the rest of the content on the page. |
Note
The fixed
and sticky
classes are there to make setting the position easy, however, instead of using those classes, you could style the admin-bar
element position in your CSS.
Currently, there are no classes that can be added to <admin-bar-button>
or <admin-bar-text>
elements.
Linking or importing the admin-bar.css
into your project sets default CSS Custom Property values. The CSS in this file is added to a CSS Cascade Layer, called admin-bar
.
If you are using CSS Cascade Layers in your project you can add the admin-bar
layer to your layer stack and then override it with another layer:
@layer reset, third-party, admin-bar, theme, layout, utilities;
@layer theme {
admin-bar {
/* Styles go here, for example: */
--admin-bar-bg: #DA00FD8C;
}
}
If you are not using CSS Cascade Layers, you can override styles without the layer at-rule, because unlayered styles have more specificity:
admin-bar {
/* Styles go here, for example: */
--admin-bar-bg: rgba(52, 215, 0, 0.5);
}
The admin-bar.css
file has comments describing what each CSS Custom Property styles. The contents of that file can be found here:
/* Added styles to CSS Cascade Layer to make it easier to override them. */
@layer admin-bar {
admin-bar {
/* Used in gradients and as a solid color in the background for `<admin-bar>` elements and button popovers. */
--admin-bar-bg-color: #000000;
/* Sets the background of the `<admin-bar>` elements and popovers using the background shorthand property,
allowing you to use a gradient, a solid color, or an image. Setting this removes the "glass" effect and transparencies in popovers. */
/*--admin-bar-bg: var(--admin-bar-bg-color);*/
/* Border radius value used in different places. */
--admin-bar-border-radius: 6px;
/* Adds an effect to blur. */
--admin-bar-backdrop-filter: blur(20px) saturate(200%);
/* The color used on hover changes. */
--admin-bar-color-highlight: oklch(0.6 0.4 83);
/* The highlight color specific to logout buttons. That can be set to
a different color to make it more obvious that the logout button is not a link. */
--admin-bar-color-highlight-logout: var(--admin-bar-color-highlight);
/* The color of text for everything but button labels.. */
--admin-bar-color-text: rgb(255 255 255 / 0.9);
/* The font stack for all text. */
--admin-bar-font-stack: system-ui, sans-serif;
/* The font size for all text. */
--admin-bar-font-size: .9rem;
/* Background for glass element, used as a fallback for browsers that don’t support `mask-image`. */
--admin-bar-glass-bg: var(--admin-bar-bg, linear-gradient(var(--admin-bar-gradient-direction), var(--admin-bar-bg-color), color-mix(in srgb, var(--admin-bar-bg-color), transparent 100%) 80%));
/* The thickness of the glass effect on admin bar. */
--admin-bar-glass-thickness: 2px;
/* The default direction of gradients. */
--admin-bar-gradient-direction: to bottom;
/* The height and width of avatar images. */
--admin-bar-avatar-size: 25px;
/* The height of the bar and all of the buttons. */
--admin-bar-height: 43px;
/* When `show-environment` is added to an `<admin-bar>` an environment
warning will appear. The default looks like yellow, striped police tape,
but you can use any CSS value used in the background shorthand property. */
--admin-bar-environment-bg: repeating-linear-gradient(
-45deg,
var(--admin-bar-environment-bg-color),
var(--admin-bar-environment-bg-color) 18px,
transparent 18px,
transparent 30px
);
/* Change just the color of the yellow stripes in the environment warning. */
--admin-bar-environment-bg-color: oklch(0.9 0.4 98);
/* The height of the environment warning */
--admin-bar-environment-height: 5px;
/* The default transition duration for all animations.
Set this to `0` to turn off transitions. */
--admin-bar-transition-duration: 0.3s;
/* Adds a box-shadow to the bar to increase visual elevation. */
/*--admin-bar-shadow: 0 0 15px color-mix(in srgb, rgb(0, 0, 0, 0.7), currentColor 10%);*/
/* Adds a box-shadow to avatar images and buttons. */
--admin-bar-shadow-elements: 0 1px 2px color-mix(in srgb, rgb(0 0 0 / 0.4), currentColor 10%), 0 3px 6px color-mix(in srgb, rgba(0 0 0 / 0.3), currentColor 10%);
/* By default, when adding the `fixed` or `sticky` class to an `<admin-bar>`,
the z-index of the element is set to `1`. Set this property if you need the
z-index to be a higher value. */
/*--admin-bar-z-index: 1;*/
/* The background of all buttons. */
--admin-bar-button-color-bg: transparent;
/* The background of the button that is currently in the hover state. */
--admin-bar-button-color-bg-hover: var(--admin-bar-button-color-text, white);
/* The text of all button labels. */
--admin-bar-button-color-text: rgb(255 255 255);
/* The background of the button popover element. */
--admin-bar-button-popover-bg: var(--admin-bar-bg, color-mix(in srgb, var(--admin-bar-bg-color), transparent 40%));
/* The `border-radius` property that changes based on the position of the popover. */
--admin-bar-button-popover-border-radius: var(--admin-bar-border-radius);
/* The value of the padding property on `admin-bar-text` components. */
--admin-bar-text-padding: 0 clamp(4px, 1vw, 13px);
/* The background for labels in `admin-bar-text` components. */
--admin-bar-text-label-color-bg: rgb(255 255 255 / 0.9);
/* The text for labels in `admin-bar-text` components. */
--admin-bar-text-label-color-text: rgb(0 0 0 / 1);
/* ====================================================================== */
/* Default styles for the `<admin-bar>` element. */
--environment-height: 0px;
display: block;
width: var(--admin-bar-width, 100%);
height: calc(var(--admin-bar-height, 43px) + var(--environment-height));
/* Add height when environment warning is enabled. */
&[show-environment] {
--environment-height: var(--admin-bar-environment-height);
}
/* Set read direction from right to left. */
&.rtl {
direction: rtl;
}
/* Fixes `<admin-bar>` to the top of page. */
&.fixed {
position: fixed;
right: 0;
left: 0;
z-index: var(--admin-bar-z-index, 1);
&:not(.bottom) {
top: 0;
}
}
/* Sticks `<admin-bar>` to the top of the page when scrolling. */
&.sticky {
position: sticky;
right: 0;
left: 0;
z-index: var(--admin-bar-z-index, 1);
&:not(.bottom) {
top: 0;
}
}
/* Moves `<admin-bar>` to the bottom of the page when using `.fixed` or `.sticky`. */
&.bottom {
--admin-bar-gradient-direction: to top;
right: 0;
bottom: 0;
left: 0;
}
/* Avoid layout shift from happening before Admin Bar Component is registered. */
&:not(:defined) {
background: var(--admin-bar-bg-color);
opacity: 0.75;
/* Hide all slot content until Admin Bar Component is registered. */
& * {
display: none;
}
}
}
@media (prefers-reduced-motion) {
admin-bar {
/* Turns off transitions for users who do not want any animations. */
--admin-bar-transition-duration: 0s;
}
}
}
This project is new and it will evolve as it grows (including adding CI automation, tests, and checks). For now, if you run into any bugs, please leave an issue on GitHub.
If you would like to contribute changes to the project, please do the following:
- Fork the branch you would like to start with (usually
main
). - Set up the project locally (using the Node version described in the
.nvmrc
file in the root). - Make your changes.
- Run
npm run test
to run type checking and to run tests. - Push your branch up and create a pull request on GitHub.
Not all pull requests will be pulled in and not all issues will get fixed, but all suggestions are welcomed.