Theme
Version
GitHub PyPI Discord
On this page

Citry UI

Citry UI gives you ready-made, styled components, such as buttons, tabs, dialogs, and form inputs, so you do not have to build and style them yourself. The Citry team maintains it. Each component renders its HTML on the server, adds its own browser behavior, and lets you change its look with CSS variables.

Citry UI is a separate package from citry, so you install it only when you want these components.

Get started

  1. Install and register Citry UI.
  2. Pick a component from the list below.
  3. Change colors and styles to match 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.

Pass request data safely

Request data is any value a visitor controls, such as a query parameter, form field, or header. A plain string you pass to a component, such as a label or a cell value, shows as text.

URL inputs check the scheme and raise ValueError for any other:

  • link inputs such as href and action accept a relative URL or an http:, https:, mailto:, sms:, or tel: URL;
  • image inputs such as src accept a relative URL or an http:, https:, blob:, or data:image/ URL.

See Check URL attributes for the other URLs on your page.

Two inputs need checks of your own:

  • Build attribute maps (attrs= and the other *_attrs= arguments) in your own code. Citry UI raises ValueError for a key such as onclick, a key the component sets itself, or a key that starts with data-citry-, data-cui-, data-cev or data-cid. Citry's browser code finds its elements by those names, so a key from request data could make it act on the element. Citry UI does not check what the other names mean.
  • Choose style values in your own code. Citry does not check them as CSS, so a value from request data can add declarations of its own, such as a background image from another site.

A component can give you attrs in slot data, such as CDialog's activator_attrs. Pass them to a <c-CButton> as they are, or add your own keys with c-attrs="{**activator_attrs, 'title': 'More'}".

Upgrade with care

Citry UI is in alpha, so a new release can change how a component looks or behaves. Read the Citry UI changelog before you upgrade, and check the component states your application depends on.

Report a problem

Report bugs, missing states, accessibility problems, and awkward APIs in the Citry issue tracker. Include the component name, the Citry UI version, your browser, and a small example that shows the problem.