All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
Contribute to the DSpace Development Fund
The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.
The DSpace User Interface (UI) is built on the Angular.io framework. All data comes from the REST API (DSpace Backend), and the final HTML pages are generated via TypeScript.
Before getting started in customizing or branding the UI, there are some basic Angular concepts to be aware of. You do not need to know Angular or TypeScript to theme or brand the UI. But, understanding a few basic concepts will allow you to better understand the folder structure / layout of the codebase.
Angular Components: In Angular, every webpage consists of a number of "components" which define the structure of a page. They are the main "building block" of any Angular application. Components are reusable across many pages. So, for example, there's only one "header" and "footer" component, even though they appear across all pages.
Each Component has:
*.component.ts
(TypeScript) file which contains the logic & name ("selector") of the component*.component.html
(HTML) file which contains the HTML markup for the component (and possibly references to other embedded components). This is also called the "template".<ds-header>
, <ds-footer>
). In DSpace's UI, every component starts with "ds-" in order to distinguish it as an out-of-the-box DSpace component. *.component.scss
(Sass / CSS) file which contains the style for the component.If you want a deeper dive into Angular concepts of Components and Templates, see https://angular.io/guide/architecture-components
The DSpace UI uses:
Familiarity with these technologies (or even just CSS + HTML) is all you need to do basic theming of the DSpace UI.
Out of the box, there are three theming layers/directories to be aware of:
src/app/
directories): The primary look & feel of DSpace (e.g. HTML layout, header/footer, etc) is defined by the HTML5 templates under this directory. Each HTML5 template is stored in a subdirectory named for the Angular component where that template is used. The base theme includes very limited styling (CSS, etc), based heavily on default Bootstrap (4.x) styling, and only allowing for minor tweaks to improve WCAG 2.1 AA accessibility.src/themes/custom
directories): This directory acts as the scaffolding or template for creating a new custom theme. It provides (empty) Angular components/templates which allow you to change the theme of individual components. Since all files are empty by default, if you enable this theme (without modifying it), it will look identical to the Base Theme.src/themes/dspace
directories): This is the default theme for DSpace 7. It's a very simple example theme providing a custom color scheme & homepage on top of the Base Theme. It's important to note that this theme ONLY provides custom CSS/images to override our Base Theme. All HTML5 templates are included at the Base Theme level, as this ensures those HTML5 templates are also available to the Custom Theme.The DSpace UI design principles & technologies are described in more detail at DSpace UI Design principles and guidelines
src/themes/custom)
. This folder contains the boilerplate code for all theme-able components. It's a scaffolding for a new theme which doesn't modify any of the "base theme" (src/app/
directories). This means that by default it's a plain Bootstrap look and feel, with a few tweaks for better accessibility.src/themes/
(choose whatever folder name you want)Modify angular.json
(in the root folder), adding your theme folder's main "theme.scss" file to the "styles" list. The below example is for a new theme folder named src/themes/mydspacesite/
"styles": [ "src/styles/startup.scss", { "input": "src/styles/base-theme.scss", "inject": false, "bundleName": "base-theme" }, ... { "input": "src/themes/mydspacesite/styles/theme.scss", "inject": false, "bundleName": "mydspacesite-theme" }, ]
NOTE: the "bundleName" for your custom them MUST use the format "${folder-name}-theme". E.g. if the folder is named "arc/themes/amazingtheme", then the "bundleName" MUST be "amazingtheme-theme"
Enable your theme: Modify your src/environments/environment.*.ts
configuration file, adding your new theme to the "themes" array in that file. Pay close attention to modify the correct environment file (e.g. modify environment.dev.ts if running in dev mode, or environment.prod.ts if running in prod mode). We recommend starting in "dev mode" (environment.dev.ts) as this mode lets you see your changes immediately in a browser without a full rebuild of the UI – see next step.
// In this example, we only show one theme enabled. It's possible to enable multiple (see below note) themes: [ { name: 'mydspacesite' }, ]
src/themes/mydspacesite/
globally. You should also comment out the default "dspace" theme, if you intend to replace it entirely.Verify your settings by starting the UI (ideally in Dev mode): At this point, you should verify the basic settings you've made all "work". We recommend doing your theme work while running the UI in "dev mode", as the UI will auto-restart anytime you save a new change. This will allow you to quickly see the impact of each change in your browser.
# Start in dev mode (which uses environment.dev.ts) yarn start:dev
Changes to the global Bootstrap variables or styles will apply to all pages / Angular components across the entire site.
styles
folder (e.g. src/themes/mydspacesite/styles
). There are four main files in that folder:_theme_sass_variable_overrides.scss
- May be used to override Bootstrap's default Sass variables. This is the file you may wish to use for most style changes. There are a large number of Bootstrap variables available which control everything from fonts, colors and the base style for all Bootstrap web components. For a full list of Bootstrap variables you can override in this file, see the node_modules/bootstrap/scss/_variables.scss
file (which is installed in your source directory when you run "yarn install"). More information may also be found in the Bootstrap Sass documentation at https://getbootstrap.com/docs/4.0/getting-started/theming/#sass_theme_css_variable_overrides.scss
- May be used to override DSpace's default CSS variables. DSpace's UI uses CSS variables for all its components. These variables all start with "--ds-*", and are listed in src/styles/_custom_variables.scss.
You can also use this file to add your own, custom CSS variables which you want to use for your theme. If you create custom variables, avoid naming them with a "--ds-*" or a "--bs-*" prefix, as those are reserved for DSpace and Bootstrap variables._global-styles.scss
- May be used to modify the global CSS/SCSS for the site. This file may be used to override the default global style contained in src/styles/_global-styles.scss
. Keep in mind, many styles can be more quickly changed by simply updating a variable in one of the above "*_variable_overrides.scss" files. So, it's often easier to use those first, where possible.theme.scss
- This just imports all the necessary Sass files to create the theme. It's unnecessary to modify directly, unless you with to add new Sass files to your theme._theme_sass_variable_overrides.scss
file. One option is to add a new import statement and modify the "$font-family-sans-serif" variable:
// Import the font (from a URL) @import url('https://fonts.googleapis.com/css?family=Source+Sans+Pro'); // Configure Bootstrap to use this font (and list a number of backup fonts to use on various systems) $font-family-sans-serif: 'Source Sans Pro', -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" !default;
assets/fonts/
folderCreate a new ".scss" file specific to your font in that folder, e.g. assets/fonts/open-sans.scss
, and use the "@font-face" CSS rule to load that font:
@font-face { font-family: "Open Sans"; src: url("/assets/fonts/OpenSans-Regular-webfont.woff2") format("woff2"), url("/assets/fonts/OpenSans-Regular-webfont.woff") format("woff"); }
Then, import that new "open-sans.scss" file and use it in the "$font-family-sans-serif" variable
// Import the font via the custom SCSS file @import '../assets/fonts/open-sans'; // Configure Bootstrap to use this font (and list a number of backup fonts to use on various systems) $font-family-sans-serif: 'Open Sans', -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" !default;
_theme_sass_variable_overrides.scss
file. node_modules/bootstrap/scss/_variables.scss
fileassets/image/
folder. Anything in this theme folder will be deployed to /assets/[theme-name]/images/
URL path.Edit your theme's app/header/header.component.ts
file. Swap the "templateUrl" property that your theme is using the local copy of "header.component.html"
@Component({ selector: 'ds-header', // styleUrls: ['header.component.scss'], styleUrls: ['../../../../app/header/header.component.scss'], // Uncomment the templateUrl which references the "header.component.html" file in your theme directory templateUrl: 'header.component.html', // Comment out the templateUrl which references the default "src/app/header/header.component.html" file. //templateUrl: '../../../../app/header/header.component.html', })
header.component.html
file will be empty by default. Copy over the default HTML code from src/app/header/header.component.html
into your version of this file.Then, modify your copy of header.component.html to use your logo. In this example, we're assuming your theme name is "mytheme" and the logo file is named "my-logo.svg"
<header> <div class="container"> <div class="d-flex flex-row justify-content-between"> <a class="navbar-brand my-2" routerLink="/home"> <!-- Modify the logo on the next line --> <img src="/assets/mytheme/images/my-logo.svg" [attr.alt]="'menu.header.image.logo' | translate"/> </a> ... </header>
<ds-search-navbar>
is the search icon in the header). You can easily comment out these tags to disable them, or move them around to change where that component appears in the header.Edit your theme's app/footer/footer.component.ts
file. Swap the "templateUrl" and "styleUrls" properties, based on which you want to modify in your theme.
@Component({ selector: 'ds-footer', // If you want to modify styles, then... // Uncomment the styleUrls which references the "footer.component.scss" file in your theme's directory // and comment out the one that references the default "src/app/footer/footer.component.scss" styleUrls: ['footer.component.scss'], //styleUrls: ['../../../../app/footer/footer.component.scss'], // If you want to modify HTML, then... // Uncomment the templateUrl which references the "footer.component.html" file in your theme's directory // and comment out the one that references the default "src/app/footer/footer.component.html" templateUrl: 'footer.component.html' //templateUrl: '../../../../app/footer/footer.component.html' })
footer.component.html
or footer.component.scss
or both.footer.component.html
file will be empty by default. Copy over the default HTML code from src/app/footer/footer.component.html
into your version of this file.footer.component.scss
file will be empty by default. Copy over the default Sass code from src/app/footer/footer.component.scss
into your version of this file.assets/images
folder. Then reference them at the /assets/[theme-name]/images/
URL path.DSpace also has a option to display a two-level footer, which is becoming more common these days. By default. DSpace just displays a small, bottom footer. But, you can enable a top footer (above that default footer) by add this line into your theme's footer.component.ts
export class FooterComponent extends BaseComponent { // This line will enable the top footer in your theme showTopFooter = true; }
This top footer appears in the footer.component.html
within a div. Notice the "*ngIf='showTopFooter'
", which only shows that div when that variable is set to "true"
<footer class="text-lg-start"> <!-- This div and everything within it only displays if showTopFooter=true --> <div *ngIf="showTopFooter" class="top-footer"> ... </div> <!-- The bottom footer always displays --> <div class="bottom-footer ..."> ... </div> </footer>
Edit your theme's app/home-page/home-news/home-news.component.ts
file. Swap the "templateUrl" and "styleUrls" properties, based on which you want to modify in your theme.
@Component({ selector: 'ds-home-news', // If you want to modify styles, then... // Uncomment the styleUrls which references the "home-news.component.scss" file in your theme's directory // and comment out the one that references the default "src/app/home-page/home-news/home-news.component.scss" styleUrls: ['./home-news.component.scss'], //styleUrls: ['../../../../../app/home-page/home-news/home-news.component.scss'], // If you want to modify HTML, then... // Uncomment the templateUrl which references the "home-news.component.html" file in your theme's directory // and comment out the one that references the default "src/app/home-page/home-news/home-news.component.html" templateUrl: './home-news.component.html' //templateUrl: '../../../../../app/home-page/home-news/home-news.component.html' })
home-news.component.html
or home-news.component.scss
or both.home-news.component.html
file will be empty by default. Copy over the default HTML code from src/app/home-page/home-news/home-news.component.html
into your version of this file.home-news.component.scss
file will be empty by default. Copy over the default Sass code from src/app/home-page/home-news/home-news.component.scss
into your version of this file.assets/images
folder. Then reference them at the /assets/[theme-name]/images/
URL path.By now, if you've followed this entire guide, you'll notice a pattern! Customizing specific DSpace UI components requires just three steps:
*.component.ts
in your theme. *.component.scss
in your theme.*.component.html
in your theme.*.component.scss
code (from src/app/
) into your theme's component.scss
file.*.component.html
code (from src/app/
) into your theme's component.html
file.assets/images
folder. Then reference them at the /assets/[theme-name]/images/
URL path.