UX

This page collects general UX requirements.

Inactive actions must be displayed as disabled rather than hidden

req~ux.disabled-vs-hidden~1

When there is functionality generally available but cannot be executed at the present time, it is shown as disabled.

Example: Button to open a link. If there is no link, the button should be shown but not enabled.

Needs: impl

Confirmation dialogs must label confirm button with action name

req~ui.dialogs.confirmation.naming~1

In confirmation dialogs, the confirm button must be labeled with the specific action name (e.g., “Download full text documents”) rather than a generic label such as “OK” or “Yes”.

Rationale: Action-specific labels eliminate ambiguity about the consequence of the button press and reduce the risk of accidental confirmation.

Needs: impl

Merge entries dialog must close automatically when single source remains

req~ux.auto-close.merge-entries~1

The merge entries dialog collects and merges data from multiple sources. In case there is only one source, it should not be shown. Since some data fetchers take time, we need to open the dialog and wait until all sources are available. As soon as only one source is available, the dialog should be closed to speed up the user’s workflow.

Needs: impl

Main table must maintain focus when switching tabs or adding libraries

req~maintable.focus~1

The main table maintains focus when adding a new library or switching between library tabs.

Rationale: Retaining focus enables immediate keyboard interaction (such as Ctrl+V paste shortcuts) without requiring the user to click with the mouse first.

Needs: impl

Main table column headers must display user-friendly titles

req~maintable.column-headers.user-friendly~1

Column headers of the main table show readable names, not raw BibTeX field names. JabRef-internal fields such as the entry type and the citation key are shown as “Entry Type” and “Citation Key”. Headers use Title Case, as an exception to the sentence-case rule for UI text, so they read like the other headers (“Author/Editor”).

Needs: impl

GUI must display error dialog upon critical startup failure

req~ux.startup.critical-error-dialog~1

If a critical error occurs before the main window is fully constructed, JabRef displays a visible error dialog in addition to logging the error.

Rationale: Digging through log files is not accessible or obvious to non-technical users (#14967).

Needs: impl

JabRef must load citation style sources on demand

req~ux.citation-styles.lazy-source-loading~1

JabRef must load built-in citation-style metadata at startup without retaining every CSL source in memory. A style’s source is loaded only when that style is used.

Needs: impl, utest

Merge entries dialog must allow selecting empty field values

req~ux.merge-entries.select-empty-field~1

When the merge entries dialog shows a field that is missing in one of the source entries, the user must be able to explicitly select that empty value so the merged entry is cleared for that field.

Needs: impl

Entry update workflow must apply confirmed merge result atomically

req~ux.update-entry-web-info.apply-merge-result~1

When a user chooses Update with bibliographic information via entry data and confirms the merge dialog, the selected merged values must be written back to the original entry as one undoable update.

Needs: impl

Library activation must keep entry preview rendering responsive

req~ux.active-library.preview-responsiveness~1

When a user activates a large library, automatic group construction and group-count evaluation must not delay rendering the selected entry preview.

Needs: impl

Consistency reports must be prepared outside JavaFX application thread

req~ux.consistency.report-background~1

Report preparation includes computing the table columns and field-presence symbols before the dialog is shown.

Needs: impl, utest

Consistency exports must run outside JavaFX application thread

req~ux.consistency.export-background~1

The user chooses a destination in the GUI before the TXT or CSV report is written in the background.

Needs: impl, utest

Consistency exports must preserve results shown in dialog

req~ux.consistency.export-snapshot~1

Entry edits or entry-type customizations after the check must not change an exported report.

Needs: impl, utest

Consistency dialog actions must navigate to original library entries

req~ux.consistency.entry-navigation~1

The dialog uses snapshots to prepare its report without replacing the entries selected for editing.

Needs: impl, utest

Consistency dialog must display fields missing from every entry

req~ux.consistency.missing-field-columns~1

Reported columns remain visible even when all entries of the selected type have the same field-presence symbol.

Context: Consistency-check output fixes.

Needs: impl, utest

Consistency dialog can restrict field columns to a BibTeX style

req~ux.consistency.bst-field-columns~2

The user chooses a .bst file and can switch between all columns and the fields its ENTRY command declares, their supported aliases, and the implicit crossref field. Switching back and forth keeps the chosen style. A pending style load preserves a later choice to show all fields. Entry type and citation key stay visible; entry types without a visible column are not offered.

Needs: impl, utest

Consistency check must compare only entries selected by an AUX file

req~ux.consistency.aux-entry-selection~2

The user chooses a LaTeX .aux file to select cited entries, including citations from nested AUX files. If exactly one .aux file lies next to the library file, it is chosen by default after the consistency dialog opens. The decision to open the dialog uses the full-library findings, regardless of the default AUX subset. A wildcard citation selects all library entries. The check recomputes differences within the selected entries and preserves the chosen field restriction. The user switches between all entries and the cited ones; switching keeps the chosen .aux file. Unknown citation keys do not select entries; a valid selection without matching entries produces an empty report. Uncited cross-reference parents do not participate in the comparison.

Reading and checking run in the background. Superseded loads stop cooperatively when the selection changes or the dialog closes. Reports share immutable field-presence snapshots and derive cell symbols on demand. A read failure preserves the previous report. Automatic-load failures are logged without opening an error dialog; explicitly selected file failures are shown to the user. An older request cannot replace a newer selection. Exports use the selected-entry report, while entry navigation targets the original library entries.

Context: AUX selection for consistency checks.

Needs: impl, utest

Group creation must allow populating new explicit group from selection

req~ux.groups.create-explicit-from-selection~1

When a user creates a new explicit group, JabRef should allow reusing the currently selected entries for that group and should keep the newly created group selected afterwards.

Needs: impl

The “Close dialog” key binding closes the dialog

req~ux.dialogs.close-key-binding~1

Pressing the “Close dialog” key binding in a dialog closes it (#8888, #15133). Its default is Esc; users can change it in the key binding preferences. Heavy-weight dialogs whose content the user builds up over time are exempt, so that a stray key press does not throw that state away. Currently, this is only the PDF viewer (“Document viewer”).

Needs: impl, utest

Open combo box popup must close without closing enclosing dialog on Escape

req~ux.combobox.escape-closes-popup-only~1

When a combobox or drop-down list (such as a CheckComboBox, ComboBox, or ChoiceBox) is open within a dialog and the user presses Escape, only the drop-down popup must be closed. The enclosing dialog must remain open (#16596).

Library save must maintain filesystem change detection after completion

req~ux.external-library-changes.after-save~1

When JabRef saves a library, it must keep observing filesystem changes, defer change detection until the save has finished, and then inspect the resulting file for external changes that require conflict resolution. Since inspecting a library file means parsing it completely, the inspection is skipped when the file’s size and modification time show that it has not changed since the last state known to match the in-memory library.

Needs: impl

Bulk entry deletion must keep main table responsive

req~ux.large-library.bulk-entry-removal~1

When a user deletes many entries from a large library, JabRef must keep the main table responsive.

Needs: impl

Text input dialogs must focus primary text field upon opening

req~ux.textdialogs.focus~1

When a dialog with text input as a main component is opened, the text field should be focused.

Needs: impl

Textual list filtering must be case-insensitive and separator-aware

req~ux.text-filtering.case-insensitive-separators~1

When users filter textual lists, matching must ignore case and treat punctuation or whitespace separators as equivalent. For example, a search for Springer lecture or SPRINGER LECTURE or springer lecture should match Springer - Lecture Notes in Computer Science.

Needs: impl

Save before closing dialog must offer diff view of unsaved changes

req~ux.close.show-diff~1

When closing a modified library, the “Save before closing” dialog should offer to show the unsaved changes compared to the file on disk, so the user can decide between saving and discarding on an informed basis.

Needs: impl

Text input dialogs must auto-paste relevant clipboard content on open

req~ux.textdialogs.autopaste~1

When a dialog with text input as a main component is opened, and it is expected that while working with it, the user will paste from clipboard, JabRef should already automatically paste it.

Example: new entry dialog by ID. It is expected that user would copy some paper ID (from browser, PDF, etc.), and then paste it in the dialog. As said above, JabRef automatically pastes the ID into the text field.

Needs: impl

New entry dialog must auto-detect clipboard identifier and focus field

req~newentry.clipboard.autofocus~1

When the “New Entry” dialog is opened:

• If the clipboard contains a valid identifier (e.g., DOI, ISBN, ArXiv, RFC):

  • The dialog automatically switches to the “Enter Identifier” tab.
  • The identifier input field is automatically filled with the clipboard content.
  • The field receives keyboard focus and its content is selected.
  • The corresponding fetcher (e.g., DOI, ISBN) is automatically selected based on the detected identifier type.

Rationale: Pre-filling and auto-focusing the detected identifier eliminates repetitive mouse clicks and tab switching when creating entries from copied DOIs or ISBNs.

Needs: impl

JabRef must bundle dual-scheme community themes out of the box

req~ux.themes.bundled-community-themes~1

The themes from https://themes.jabref.org/ that cover both color schemes are bundled with JabRef and appear in the theme selection next to the built-in themes, without the user having to download a CSS file.

Needs: impl

Library tabs must display icon indicating library storage format

req~ux.tabs.library-kind-icon~1

Every library tab carries an icon: one for a BibTeX library, one for a BibLaTeX library, and one for a shared database. A shared database shows the database icon regardless of its mode.

Needs: impl, utest

Preferences walkthroughs must open preferences dialog directly

req~ux.walkthrough.preferences-direct~1

Walkthroughs that require preferences must open the preferences dialog directly, so they can start regardless of the platform menu presentation.

Needs: impl

Groups walkthrough must prepare example library and groups UI state

req~ux.walkthrough.groups-preparation~1

The groups walkthrough must open its bundled example library, display the Groups pane, and clear the current search before guiding the user.

Needs: impl

Donation prompt returns every six months

req~ux.donation.recurring-prompt~1

JabRef asks for a donation six months after the first launch and every six months afterwards. Dismissing the prompt hides it until the next time; “Dismiss forever” stops it for good.

Needs: impl

Library tab switches must preserve each library’s selected groups

req~ux.groups.library-switch-preserves-selection~1

Rationale: The user must be able to switch between libraries and still see the same groups selected (#1104).

Needs: impl, utest

Shared library group updates must preserve selected groups

req~ux.groups.shared-update-preserves-selection~1

When a shared library receives a group-tree update, groups that remain in the updated tree must remain selected.

Needs: impl, utest

Assigning an already used keyboard shortcut must require confirmation

req~ux.keybindings.duplicate-warning~1

When a user assigns a keyboard shortcut that is already used by other actions, JabRef warns the user, names these actions and lets the user cancel, keep both or replace the existing assignments (#17240).

Needs: impl, utest