All documentation
Tags and organization/02

Star ratings

Free

Mark favorites directly on items.

Star ratings are Free review marks for board items. FenSight stores each rating as a rating tag, draws gold star badges on eligible file-backed items, and lets those same ratings feed tag filters, board persistence, Pro clustering, and search workflows.

Screenshot coming soon

FenSight board item with a gold star rating badge, the Properties dock Rating row, and rating tags in the Tags dock

Screenshot placeholder. Expected production asset: /docs/screenshots/star-ratings.png.

Star rating access paths

Toolbar

Bottom tool rail -> Select (V) -> click a file-backed item's star row

The canvas star hit-test runs only in the default select/object flow: no active drawing, connector, pan, or other canvas tool, and not Group selection mode.

Toolbar

Bottom tool rail -> Select (V) -> select one file-backed item -> hover its bottom-left star row

Single selection enables the larger hover rating overlay. Click one of the five stars to rate the selected item.

Dock

Properties dock -> Rating

Shows five star buttons for the current selection. Clicking a star applies that rating through the same tag-backed rating pipeline.

Dock

Tags dock -> My Tags -> rating pill

Ratings appear as My Tags pills because they are stored as rating:1 through rating:5 item tags.

Toolbar

Layout dropdown -> Cluster: Star Rating

Pro layout mode that groups rated layout participants by their saved rating, then places unrated items at the end.

Toolbar

Layout dropdown -> Custom Cluster Layout -> Clustering Heuristic -> Star Rating

Pro custom-cluster heuristic. The in-app tooltip says unrated items go into an Other cluster.

Rating controls

ControlUser-facing behaviorTechnical behavior
Canvas star badgeFree
Lets you set a rating directly on a visible board item.Pointer-down handling checks star rectangles before normal item hit testing when the canvas tool is None and Group selection mode is off. Hidden-by-tag and hidden-by-extension items are skipped.
Hover rating overlayFree
Shows a larger five-star row while reviewing one selected item.The overlay is available only for a single selected file-backed item and is cleared during panning, dragging, resizing, connector editing, and other interactive states.
Properties dock -> RatingFree
Applies a rating from the selected item's properties.RatingStar1 through RatingStar5 raise RatingChanged with values 1 through 5. FenSight applies the chosen rating to the current selected items and refreshes the Tags dock, star UI, and Properties dock.
Click the same rating againFree
Clears the current rating.ApplyRating and SetItemStarRating both remove existing rating: tags first. If the requested rating matches the current rating, FenSight leaves the item unrated and sets StarRating to 0.
First rating toastFree
Shows a one-time hint after the first rating interaction.FenSight saves RatingTooltipShown in settings and shows: Click a star to rate. Ratings are filterable tags.
Undo / RedoFree
Restores rating edits with normal board history.Rating changes capture tag history with each target's Tags set and StarRating, then record the operation as Change rating.

What can be rated

TargetUser-facing behaviorTechnical behavior
File-backed board itemsFree
Images, videos, sequences, documents, board previews, audio, and other file-backed items can show visible star badges.BoardSurface.GetStarRects returns star hit rectangles only when the item is file-backed and large enough on screen.
Small or far-zoomed itemsFree
May omit the rating row until there is enough screen space.Persistent badges use a star size clamped from 7 to 12 pixels and are skipped when the five-star row would exceed half the item's screen width. The hover overlay uses a similar width gate.
Labels, shapes, and strokesFree
Do not participate in the visible canvas star-badge workflow.Canvas rating hit tests and star rectangles skip LabelItem, ShapeItem, and StrokeItem-style non-file annotations. Use star ratings for file-backed review items when you need visible board badges.
Filtered-out itemsFree
Cannot be rated from the canvas while hidden.The canvas rating hit-test ignores items with HiddenByTagFilter or HiddenByExtensionFilter set.
Group selection modeFree
Disables direct canvas star clicking.The pointer-down star hit-test is bypassed when Group selection mode is active. Switch back to Object selection mode to rate through the canvas badge.

Storage and tag behavior

BehaviorUser-facing behaviorTechnical behavior
Rating tagsFree
Make ratings available anywhere tags are available.The rating is stored as exactly one rating:1 through rating:5 tag. GetItemRating parses the first rating: tag it finds and clamps the parsed value to 1 through 5.
Board saveFree
Reopens ratings with the board.Board persistence writes StarRating from GetItemRating when a rating is present, and also saves non-label item Tags. On load, an existing rating tag wins; the saved StarRating field is used as a compatibility fallback.
Tags dockFree
Shows ratings as filterable My Tags pills.RebuildAllTags gathers tags from file-backed items. The Tags dock renders rating:1 through rating:5 as gold rating-style pills in My Tags.
Properties tag chipsFree
Keeps rating tags out of the normal user-tag chip list.The Properties dock filters out tags starting with rating: before building ordinary user tag chips, so the Rating row remains the primary Properties-dock control.
Clear all selected tagsFree
Can remove ratings from selected items.Tags dock -> Clear removes checked tags, or every tag when no pill is checked. Because ratings are tags, clearing all tags removes rating: tags too.
Edit Tags...Free
Can replace or remove ratings if the rating tag is not kept.The Edit Tags dialog replaces the target items' tag sets from the parsed text. Keeping rating:3 preserves a three-star rating; omitting rating tags leaves the item unrated.

Canvas rendering

SurfaceUser-facing behaviorTechnical behavior
Persistent star badgeFree
Marks rated items at a glance while scanning the board.BoardSurface draws a small bottom-left five-star strip over a dark rounded background. Filled stars use the item's StarRating; unrated items draw no badge.
Hover previewFree
Previews the rating you are about to set.When hovering the overlay, FenSight fills up to the higher of the hovered star index plus one and the current rating.
Click animationFree
Gives immediate feedback after setting a rating.TriggerStarAnimation scales the clicked star for about 150 ms, peaking around 1.4x scale, then returns to the normal strip.
Interaction performanceFree
Avoids extra rating drawing during heavy board interactions.Star badges are normally skipped while the board is in an interactive state unless SmoothInteractionUpdates is enabled.

Downstream use

WorkflowUser-facing behaviorTechnical behavior
Tag filteringFree
Filters the board to rated items or specific rating levels.Checked rating pills join the same _activeTagFilters set as other user tags. Show Tagged hides non-matching non-label items using the visible Tags dock's OR filter behavior.
Cluster: Star RatingPro
Groups board items by rating for review passes.LayoutClusterByStarRating groups layout participants with StarRating greater than 0 by rating in ascending order, then appends unrated items as the final group.
Custom Cluster Layout -> Star RatingPro
Combines rating groups with chosen custom cluster shapes and label settings.The Custom Cluster Layout heuristic list includes Star Rating. The saved heuristic maps back to the built-in Cluster: Star Rating layout.
AI semantic searchPro
Can use rating tags as part of searchable item context.Semantic search scoring includes user tag text along with filename/path text, AI tags, captions, and embeddings.
Organize and export workflowsFree
Can carry rating state through tag-aware review and export paths.Organize preview rows expose board item tags, and exported board context includes top tag counts. Ratings appear there through their rating: tags.

Ratings are not a separate favorite database. They are board item tags named rating:1 through rating:5, with StarRating kept in sync for drawing and compatibility.

Connected guides

Follow these related pages when the workflow crosses into setup, search, organization, export, security, or another board-level system.