Theme
Version
GitHub PyPI Discord
On this page

Citry UI

Citry UI is the first-party styled component library for Citry. Its components render useful HTML on the server, add browser behavior through Citry's client runtime, and expose documented CSS variables and parts for application themes.

The library is a separate Python distribution. Install it when an application wants the built-in design system, while keeping the core citry package small.

Start with the library

  1. Install and register Citry UI.
  2. Use a component from the Components section.
  3. Set colors, spacing, and component parts for your application.

Components

Actions

  • Button - Render styled native actions, links, and form submitters with Citry UI Button.
  • Button Group - Arrange related Citry UI actions as one named group.
  • Split Button - Keep one dominant action visible beside a Menu of related actions.
  • Toggle - Build standalone or grouped pressed Buttons with Citry UI.
  • Toolbar - Group persistent controls under one name and one page Tab stop.

Forms and inputs

  • Calendar - Select one canonical date in an inline locale-aware calendar grid.
  • Cascader - Select one path through a finite server-rendered hierarchy.
  • Checkbox - Choose independent Boolean options with native forms, mixed state, and controlled browser checkedness.
  • Color Picker - Select an opaque solid sRGB color with native form fallback.
  • Combobox - Search a local or remote collection and submit one stable option value.
  • DateInput - Collect one canonical calendar date with the browser's native date control.
  • DatePicker - Choose one canonical date from a localized popup Calendar.
  • DateRange - Choose two ordered canonical dates as one localized range.
  • Editable - Edit one short text value in place without giving up native form behavior.
  • Field and Input - Build labelled native text controls with Citry UI Field and Input.
  • File input and drop - Select files with a native picker or an accessible drop-backed picker.
  • Form - Compose native submission, validation, reset, and shared control state with Citry UI Form.
  • Form Collection - Compose keyed repeatable field groups inside one real form with accessible add remove and reorder requests.
  • Listbox - Choose one or more values from a persistent collection.
  • MultiSelect - Choose several fixed values from a compact, styled form control.
  • Native Select - Choose one value with native keyboard, touch, forms, validation, and an optional controlled browser value.
  • NumberInput - Edit and submit an exact decimal quantity with localized spinbutton behavior.
  • PinInput - Capture fixed-length verification and recovery codes without losing native input behavior.
  • Radio - Select one visible option with native Citry UI Radio Groups and Radios.
  • Rating - Select or display an exact localized score with native radio Form behavior.
  • Select - Choose one value from a compact, styled form control.
  • Sliders - Use CSlider to choose one value from a bounded exact-decimal scale. Use CRangeSlider when the user chooses an ordered lower and upper value.
  • Switch - Change an immediate on or off setting with a native Citry UI Switch.
  • TagsInput - Create and submit an ordered list of free-form text tags.
  • Textarea - Enter multiline plain text with native editing, forms, validation, and optional browser control.
  • TimeInput - Collect one canonical wall-clock time with the browser's native time control.
  • TimePicker - Select one canonical wall-clock time from a localized finite popup list.
  • Transfer List - Build an ordered chosen set with an accessible, form-capable Citry UI PickList.

Layout

  • Col and Row - Arrange Citry UI content in predictable vertical columns and wrapping horizontal rows.
  • Container and Grid - Constrain page content, build responsive equal grids, and add asymmetric spans when needed.
  • Divider - Separate sections semantically or visually with Citry UI.
  • ScrollArea - Keep bounded content reachable through native scrolling.
  • Splitter - Resize two or more adjacent application panels.

Data display

  • Avatar - Present image identities with explicit names and reliable fallbacks.
  • Badge - Present compact status, category, count, and metadata labels with Citry UI.
  • Card - Group related content, media, metadata, and actions in a flexible Citry UI surface.
  • Carousel - Browse composed content with native Scroll Snap and explicit controls.
  • Data Grid - Navigate, sort, select, edit, and server-window tabular application data with Citry UI.
  • Icon - Render a consistent, accessible set of local SVG symbols with Citry UI Icon.
  • Image - Render native responsive images with stable geometry and explicit alternative text.
  • Infinite Scroll - Request more server-owned results automatically while retaining a real Load more fallback.
  • List - Compose semantic content, navigation, and action lists with Citry UI.
  • Sortable - Reorder server-rendered items with pointer, touch, or keyboard while preserving native form order.
  • Table - Present finite server-owned records in a styled native Table.
  • Tag and TagGroup - Present descriptive, selectable, actionable, and removable Tag collections.
  • Timeline - Present histories, activity, milestones, and status sequences with Citry UI.
  • Tree - Explore and select hierarchical application data.
  • Tree Grid - Navigate expandable and selectable hierarchical records in aligned columns.
  • Virtual List - Defer off-screen rendering or supply a true server-rendered collection window with Citry UI.

Navigation

  • Breadcrumbs - Show hierarchical page location with semantic Citry UI Breadcrumbs.
  • NavigationMenu - Compose native website navigation with rich disclosure panels.
  • Pagination - Navigate finite page sequences with native links or client-owned controls.
  • Sidebar - Build persistent, rail, and collapsible application sidebars with Citry UI.
  • Stepper - Communicate and optionally navigate ordered workflow progress.
  • Tabs - Organize keyboard-accessible views with Citry UI Tabs.

Feedback and status

  • Alert - Present persistent feedback with clear intent, optional actions, and deliberate announcement urgency.
  • Progress - Communicate determinate and indeterminate task progress with a native Citry UI progress element.
  • Skeleton - Compose precise loading placeholders from visible primitives.
  • Spinner - Show compact unknown-duration activity with a labelled Citry UI Spinner.
  • Toast - Deliver queued, timed application feedback with Citry UI.

Overlays and disclosure

  • Accordion - Organize related sections with native headings, controlled expansion, stable panel content, and nested groups.
  • AlertDialog - Ask for an immediate cancel-or-action decision in an urgent modal prompt.
  • CommandPalette - Search and run grouped application commands in a modal dialog.
  • ContextMenu - Offer target-relative application commands while preserving browser context actions.
  • Dialog - Build accessible native modal workflows with Citry UI Dialog.
  • Disclosure - Reveal one independent block of supporting content.
  • Drawer - Build accessible modal side Drawers and Sheets with Citry UI.
  • HoverCard - Preview supplementary content behind a link or control.
  • Menu - Present commands, links, application choices, and nested command collections from one Button.
  • Popover - Place accessible interactive content beside a Button with Citry UI Popover.
  • Tooltip - Add accessible, noninteractive descriptions to focusable controls with Citry UI Tooltip.
  • Tour - Build polished, target-aware product walkthroughs with Citry UI.

Citry UI is currently a preview. Review the package version before upgrading and test the component states your application depends on.

Help shape Citry UI

The 0.2.0 release is an early-access alpha. Report bugs, missing states, accessibility problems, and awkward APIs in the Citry issue tracker. Include the component name, Citry UI version, browser, and a small reproduction when possible.