Skip to content

Custom HTML Graph Tooltip Prop #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 2, 2025
Merged

Custom HTML Graph Tooltip Prop #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
47a93b9
chore(docs): fixed props anchor tag hierarchy in docs
TomPlum Jul 6, 2025
ff590a8
chore(deps): package-lock.json changes after install
TomPlum Nov 2, 2025
7eca164
feat(graph): exposed custom tooltip prop on HTML graph (#102)
TomPlum Nov 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
221 changes: 131 additions & 90 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,20 +30,21 @@ A flexible and interactive React component for visualising Git commit history. D
* [GitLogPaged](#gitlogpaged)
* [Optional](#optional)
* [GitLog](#gitlog-1)
* [GitLogPaged](#gitlogpaged-1)
* [GitLogStylingProps](#gitlogstylingprops)
* [GitLogPaging](#gitlogpaging)
* [GitLogIndexStatus](#gitlogindexstatus)
* [GitLogUrlBuilder](#gitlogurlbuilder)
* [CommitFilter](#commitfilter)
* [GitLogPaged](#gitlogpaged-1)
* [GraphHTMLGrid](#graphhtmlgrid)
* [CustomCommitNode](#customcommitnode)
* [GraphCanvas2D](#graphcanvas2d)
* [NodeTheme](#nodetheme)
* [Table](#table)
* [GitLogTableStylingProps](#gitlogtablestylingprops)
* [CustomTableRow](#customtablerow)
* [CustomCommitNode](#customcommitnode)
* [BreakPointTheme](#breakpointtheme)
* [Common Types](#common-types)
* [GitLogStylingProps](#gitlogstylingprops)
* [GitLogIndexStatus](#gitlogindexstatus)
* [GitLogUrlBuilder](#gitlogurlbuilder)
* [CommitFilter](#commitfilter)
* [NodeTheme](#nodetheme)
* [BreakPointTheme](#breakpointtheme)
* [Development](#development)
* [References](#references)
* [Roadmap](#roadmap)
Expand Down Expand Up @@ -303,6 +304,13 @@ All components have optional props to further configure the log.
| `showGitIndex` | `boolean` | Enables the Git index "pseudo-commit' entry above the HEAD commit. |
| `filter` | [`CommitFilter<T>`](#commitfilter) | Filters the commits in the log based on the response from the function. |

#### GitLogPaging

| Prop | Type | Description |
|--------|----------|-------------------------------------------------|
| `size` | `number` | The number of rows to show per page. |
| `page` | `number` | The page number to display (first page is `0`). |

### GitLogPaged

| Property | Type | Description |
Expand All @@ -322,52 +330,6 @@ All components have optional props to further configure the log.
| `showGitIndex` | `boolean` | Enables the Git index "pseudo-commit' entry above the HEAD commit. |
| `filter` | [`CommitFilter<T>`](#commitfilter) | Filters the commits in the log based on the response from the function. |


#### GitLogStylingProps
| Property | Type | Description |
|-------------------|-----------------|--------------------------------------------------------------------------------|
| `containerClass` | `string` | Class name for the wrapping `<div>` containing branches, graph, and log table. |
| `containerStyles` | `CSSProperties` | React CSS styling object for the wrapping container `<div>`. |

#### GitLogPaging

| Prop | Type | Description |
|--------|----------|-------------------------------------------------|
| `size` | `number` | The number of rows to show per page. |
| `page` | `number` | The page number to display (first page is `0`). |

#### GitLogIndexStatus

| Prop | Type | Description |
|------------|----------|---------------------------------------------------------------------------|
| `added` | `number` | The number of added files in the git index for the checked-out branch. |
| `deleted` | `number` | The number of deleted files in the git index for the checked-out branch. |
| `modified` | `number` | The number of modified files in the git index for the checked-out branch. |

#### GitLogUrlBuilder

A function with the following signature
```typescript
type GitLogUrlBuilder = (args: GitLogUrlBuilderArgs) => GitLogUrls
```
Returns an object of type `GitLogUrls` with the following fields.

| Prop | Type | Description |
|------------|----------|------------------------------------------------------------------------------------------|
| `commit` | `string` | A resolved URL to a particular commit hash on the external Git providers remote website. |
| `branch` | `string` | A resolved URL to a branch on the external Git providers remote website. |

#### CommitFilter

A function with the following signature
```typescript
type CommitFilter<T> = (commits: Commit<T>[]) => Commit<T>[]
```

Is passed the array of `Commit<T>` objects from the log based on the current pagination configuration and must return the filtered array based on your own domain-specific behaviour.

The logs' subcomponents will respond accordingly based on the filtered list of commits.

### GraphHTMLGrid

| Property | Type | Description |
Expand All @@ -381,6 +343,80 @@ The logs' subcomponents will respond accordingly based on the filtered list of c
| `highlightedBackgroundHeight` | `number` | The height, in pixels, of the background colour of a row that is being previewed or has been selected. |
| `node` | [`CustomCommitNode`](#customcommitnode) | A function that returns a custom commit node implementation used by the graph. |
| `breakPointTheme` | [`BreakPointTheme`](#breakpointtheme) | Changes how the break-points between rows render when the log is being filtered. |
| `tooltip` | [`CustomTooltip`](#customtooltip) | Overrides the graph node tooltip with a custom implementation. Commit metadata is injected. |

#### CustomCommitNode

A function with the following signature:
```typescript
type CustomCommitNode = (props: CustomCommitNodeProps) => ReactElement
```

For example:
```typescript jsx
<GitLog.GraphHTMLGrid
nodeSize={25}
node={({ nodeSize, colour, isIndexPseudoNode, rowIndex }) => (
<div
className={styles.Node}
style={{
width: nodeSize,
height: nodeSize,
background: `url('https://placecats.com/${images[rowIndex % images.length]}/50/50?fit=contain&position=top') 50% 50%`,
border: `2px ${isIndexPseudoNode ? 'dotted' : 'solid'} ${colour}`
}}
/>
)}
/>
```

The following properties are injected into the functions `props` argument:

| Property | Type | Description |
|---------------------|-----------|---------------------------------------------------------------------------------------------------------|
| `commit` | `Commit` | Details of the commit that the node is being rendered for. |
| `colour` | `string` | The colour of the commit based on the column in its and the theme. |
| `rowIndex` | `number` | The (zero-based) index of the row that the node is in. |
| `columnIndex` | `number` | The (zero-based) index of the column that the node is in. |
| `nodeSize` | `number` | The diameter (in pixels) of the node. This defaults but can be changed in the graph props. |
| `isIndexPseudoNode` | `boolean` | Denotes whether the node is the "pseudo node" added above the head to represent the working tree index. |

#### CustomTooltip

A function with the following signature:
```typescript
type CustomTooltip = (props: CustomTooltipProps) => ReactElement<HTMLElement>
```

For example:
```typescript jsx
<GitLog.GraphHTMLGrid
showCommitNodeTooltips
tooltip={({ commit, backgroundColour, borderColour }) => (
<div
data-testid='my-custom-tooltip'
style={{
border: `2px solid ${borderColour}`,
backgroundColor: backgroundColour,
color: 'white',
padding: '20px 10px',
borderRadius: '5px'
}}
>
<p>My Custom Tooltip</p>
<p>{commit.message}</p>
</div>
)}
/>
```

The following properties are injected into the functions `props` argument:

| Property | Type | Description |
|--------------------|----------|-------------------------------------------------------------------------------|
| `commit` | `Commit` | Details of the commit that the tooltip is being rendered for. |
| `borderColour` | `string` | The border colour of the commit based on the column in its and the theme. |
| `backgroundColour` | `number` | The background colour of the commit based on the column in its and the theme. |

### GraphCanvas2D

Expand All @@ -392,13 +428,6 @@ The logs' subcomponents will respond accordingly based on the filtered list of c
| `enableResize` | `boolean` | Enables horizontal resizing of the graph. Default: `false`. |
| `breakPointTheme` | [`BreakPointTheme`](#breakpointtheme) | Changes how the break-points between rows render when the log is being filtered. |

#### NodeTheme

| Prop | Type | Description |
|-----------|----------|-----------------------------------------------------------------------|
| `default` | `string` | The default theme where nodes change their style based on their type. |
| `plain` | `string` | All nodes look the same, except for their colours. |

### Table

| Property | Type | Description |
Expand Down Expand Up @@ -460,43 +489,55 @@ The following properties are injected into the functions `props` argument:
| `previewed` | `boolean` | Whether the row is previewed (is being hovered over). |
| `backgroundColour` | `string` | The colour of the background as is normally applied to the table row. |

#### CustomCommitNode
## Common Types

A function with the following signature:
### GitLogStylingProps
| Property | Type | Description |
|-------------------|-----------------|--------------------------------------------------------------------------------|
| `containerClass` | `string` | Class name for the wrapping `<div>` containing branches, graph, and log table. |
| `containerStyles` | `CSSProperties` | React CSS styling object for the wrapping container `<div>`. |


### GitLogIndexStatus

| Prop | Type | Description |
|------------|----------|---------------------------------------------------------------------------|
| `added` | `number` | The number of added files in the git index for the checked-out branch. |
| `deleted` | `number` | The number of deleted files in the git index for the checked-out branch. |
| `modified` | `number` | The number of modified files in the git index for the checked-out branch. |

### GitLogUrlBuilder

A function with the following signature
```typescript
type CustomCommitNode = (props: CustomCommitNodeProps) => ReactElement
type GitLogUrlBuilder = (args: GitLogUrlBuilderArgs) => GitLogUrls
```
Returns an object of type `GitLogUrls` with the following fields.

For example:
```typescript jsx
<GitLog.GraphHTMLGrid
nodeSize={25}
node={({ nodeSize, colour, isIndexPseudoNode, rowIndex }) => (
<div
className={styles.Node}
style={{
width: nodeSize,
height: nodeSize,
background: `url('https://placecats.com/${images[rowIndex % images.length]}/50/50?fit=contain&position=top') 50% 50%`,
border: `2px ${isIndexPseudoNode ? 'dotted' : 'solid'} ${colour}`
}}
/>
)}
/>
| Prop | Type | Description |
|------------|----------|------------------------------------------------------------------------------------------|
| `commit` | `string` | A resolved URL to a particular commit hash on the external Git providers remote website. |
| `branch` | `string` | A resolved URL to a branch on the external Git providers remote website. |

### CommitFilter

A function with the following signature
```typescript
type CommitFilter<T> = (commits: Commit<T>[]) => Commit<T>[]
```

The following properties are injected into the functions `props` argument:
Is passed the array of `Commit<T>` objects from the log based on the current pagination configuration and must return the filtered array based on your own domain-specific behaviour.

| Property | Type | Description |
|---------------------|-----------|---------------------------------------------------------------------------------------------------------|
| `commit` | `Commit` | Details of the commit that the node is being rendered for. |
| `colour` | `string` | The colour of the commit based on the column in its and the theme. |
| `rowIndex` | `number` | The (zero-based) index of the row that the node is in. |
| `columnIndex` | `number` | The (zero-based) index of the column that the node is in. |
| `nodeSize` | `number` | The diameter (in pixels) of the node. This defaults but can be changed in the graph props. |
| `isIndexPseudoNode` | `boolean` | Denotes whether the node is the "pseudo node" added above the head to represent the working tree index. |
The logs' subcomponents will respond accordingly based on the filtered list of commits.

### NodeTheme

| Prop | Type | Description |
|-----------|----------|-----------------------------------------------------------------------|
| `default` | `string` | The default theme where nodes change their style based on their type. |
| `plain` | `string` | All nodes look the same, except for their colours. |

#### BreakPointTheme
### BreakPointTheme

The following themes are available:

Expand Down
Loading